Lehentasun-laguntzaileak

Zer eraikiko duzun

Erabiltzaileek hizkuntza eta testu-tamaina aukeratzen dituzten ezarpen-panel bat — dokumentu osoari aplikatzen zaizkion, bisiten artean irauten duten eta bi osagai eta CSS lerro gutxi batzuk kostatzen dizkizuten aukerak. 15 minutu inguru.

Hasi aurretik

Osatu framework tutoriala zure stack-erako. Beheko laginak Svelte-koak dira; React, Vue, Angular, HTML, Nunjucks eta Blazor laguntzaileak kontratuz kontratu datoz bat.

Partekatzen duten forma

• WAI-ARIA APG zerrenda-koadro bat irekitzen duen ikono-botoi buru gabea (edo, date-time-picker-erako, data-hautatzaile elkarrizketa) — natiborik ez <select>, beraz framework guztiek teklatu-portaera eta estilo-gako berdinak dituzte.
• Klase-gako bat pakete bakoitzeko (.locale-picker, .text-size-picker, .share-picker, .date-time-picker), CSSrik bidali gabe.
• SSR-rako segurua: DOM idazketak mount/effect bizi-zikloan baino ez dira gertatzen.
• i18n-rako garbia: erabiltzaileak ikusten duen kate guztiak propa dira.
• Svelte (kanonikoa), React, Vue, Angular, HTML elementu pertsonalizatua, Nunjucks eta Blazor-erako eskuragarri — kontratu bera bakoitzean.

theme-picker, locale-picker eta text-size-picker bakoitzak erabiltzaile- lehentasun bat du bere gain hasieratik amaierara (hautaketa, DOMean aplikazioa, aukerako localStorage iraunkortasuna storageKey propa bidez). share-picker eta date-time-picker mota desberdinekoak dira: share-picker-ek ekintza bat du bere gain — ez dio ezer aplikatzen dokumentuari eta ez du ezer gordetzen — eta date-time-picker-ek formulario-baliobat, formulario bateko data datua baita, ez lehentasuna.

locale-picker — hizkuntza eta norabidea

Erabiltzaileari locale bat aukeratzen uzten dio, eta gero idazten du lang eta dir dokumentuaren erroan zure i18n liburutegiak, zure CSSak eta teknologia lagungarriek guztiek jarrai dezaten. RTL automatikoki detektatzen da arabierarako, hebreerarako eta eskuinetik ezkerrerako beste idazkerarako. Seinalatzean soilik zentratzen da — itzulpena zure i18n liburutegiak kudeatzen du.

<script>
  import LocalePicker from "@lilydesignsystem/svelte-locale-picker";

  let locale = $state("en-US");
</script>

<LocalePicker
  label="Language"
  locales={["en-US", "fr", "ar", "he", "ja"]}
  bind:value={locale}
  storageKey="my-app-locale"
/>

Aukerek etiketak locale-izenen taula integratu batetik hartzen dituzte (gainidatz daiteke honen bidez: localeLabels), aukera bakoitzak bere lang atributua du pantaila-irakurgailuek “Français” frantsesez ahoskatzeko, eta azpimarra duten kodeek, adibidez en_US galerarik gabe joan-etorria egiten dute BCP 47-ra en-US. Konektatu onChange (edo lotutako balioa) i18next, Paraglide, vue-i18n edo erabiltzen duzun edozeinekin.

text-size-picker — irakurleak kontrolatutako tamaina

Minutuetan lortzen den irisgarritasun-irabazi bat: laguntzaileak ezartzen du data-text-size="{slug}" dokumentuaren erroan eta zure CSSak balio bakoitza tamaina batera mapatzen du.

<script>
  import TextSizePicker from "@lilydesignsystem/svelte-text-size-picker";
</script>

<TextSizePicker
  label="Text size"
  sizes={["small", "medium", "large", "x-large"]}
  storageKey="my-app-text-size"
/>

:root[data-text-size="small"]   { font-size: 87.5%; }
:root[data-text-size="medium"]  { font-size: 100%; }
:root[data-text-size="large"]   { font-size: 112.5%; }
:root[data-text-size="x-large"] { font-size: 125%; }

Neurtu zure diseinua hemen: rem eta aplikazio osoa erabiltzailearen aukerarekin eskalatzen da. Etiketak slug-etatik sortzen dira maiuskulaz (“X Large”) edo honekin gainidazten dira: sizeLabels.

share-picker — bidali orri hau

Ikur bakarreko botoi bat, gailuaren partekatze-orri natiboa irekitzen duena dagoen tokian, eta bestela zuk emandako helmugen zerrendara itzultzen dena, gehi URLa kopiatzeko ekintza. Ez du sare sozialen URLrik bidaltzen — zure produktuan zein sare egon behar diren zure erabakia da, ez diseinu-sistemarena.

<script>
  import SharePicker from "@lilydesignsystem/svelte-share-picker";

  const targets = [
    { id: "mastodon", label: "Mastodon",
      href: (url, title) => `https://mastodon.social/share?text=${encodeURIComponent(title)}%20${encodeURIComponent(url)}` },
    { id: "email", label: "Email",
      href: (url, title) => `mailto:?subject=${encodeURIComponent(title)}&body=${encodeURIComponent(url)}`, newTab: false },
  ];
</script>

<SharePicker
  label="Share this page"
  title="An article worth reading"
  {targets}
  copyLabel="Copy link"
  copiedLabel="Link copied"
/>

url lehenetsia da location.hrefberaz kasu arruntak ez du kableatzerik behar. Behartu bide bat honekin: strategy="list" edo strategy="native" probetarako edo pantaila-argazkietarako plataformen artean portaera koherentea behar duzunean.

date-time-picker — data bat, ordu bat, edo biak

Idatz dezakezun testu-eremu bat, gehi WAI-ARIA APG data-hautatzaile elkarrizketa irekitzen duen ikono-botoi bat. Locale-aren arabera zuzena eraikuntzaz — hilabete-izenak, asteko egun-izenak, asteko lehen eguna eta 12 edo 24 orduko erlojua hemendik datoz guztiak: Intl — eta balioa beti ISO kate ordenagarria da, ordu-zonarik gabe: "2026-03-15" honetarako mode="date", "09:30" honetarako mode="time", "2026-03-15T09:30" honetarako mode="datetime".

<script>
  import DateTimePicker from "@lilydesignsystem/svelte-date-time-picker";

  let appointment = $state("");
</script>

<DateTimePicker
  inputId="appointment"
  name="appointment"
  label="Choose an appointment date"
  locale="en-GB"
  bind:value={appointment}
  labels={{
    previousYear: "Previous year",
    previousMonth: "Previous month",
    nextMonth: "Next month",
    nextYear: "Next year",
    confirm: "OK",
    cancel: "Cancel",
  }}
/>

ISO balioa honek bidaltzen duenaren berdina da: <input type="date"> , beraz kontrol natiboa sartu edo atera dezakezu zure backend-ari ukitu gabe.

motion-picker — errespetatu mugimendu murriztua

Laguntzaileak ezartzen du data-motion="{slug}" dokumentuaren erroan. Bere lehen balioa bisitariaren sistema eragilearen ezarpenetik dator prefers-reduced-motion — beti, aukerako banderarik gabe, mugimendua benetako irisgarritasun-beharra delako (WCAG 2.3.3). Zure CSSak eta script-ek erabakitzen dute zer kentzen den.

<script>
  import MotionPicker from "@lilydesignsystem/svelte-motion-picker";
</script>

<MotionPicker
  label="Motion"
  motions={["no-preference", "reduce"]}
  storageKey="my-app-motion"
/>

:root[data-motion="reduce"] *,
:root[data-motion="reduce"] *::before,
:root[data-motion="reduce"] *::after {
  animation: none !important;
  transition: none !important;
  scroll-behavior: auto !important;
}

search-picker — bidetik kentzen den bilaketa-koadroa

Bilaketa-eremu bat irekitzen duen ikono-botoia. Return sakatzeak, edo eremuaren ondoko ⏎ botoiak, GET eskaera soil batekin nabigatzen du hona: /?<text> (testua mozten eta URI-kodetzen da; kontsulta hutsak ez doa inora). Bere hiru izen irisgarriak beharrezkoak dira, laguntzaileak ez baitu ingelesik bidaltzen.

<script>
  import SearchPicker from "@lilydesignsystem/svelte-search-picker";
  import { goto } from "$app/navigation";
</script>

<SearchPicker
  label="Search this site"
  inputLabel="Search terms"
  submitLabel="Search"
  placeholder="Search…"
  action="/search"
  navigate={(href) => goto(href)}
/>

action bidea aldatzen du (/search?foo), eta navigate nabigazioa aplikazioan mantentzen du; hori gabe laguntzaileak deitzen du location.assign.

picker-bar — goiburuko errenkada osoa aldi berean

picker-bar bilaketa, gaia, locale-a, testu-tamaina eta partekatzea errenkada bakarrean errendatzen ditu, erreferentzia-gaien multzo osoarekin eta zazpi mailako testu-eskalarekin aurrekonfiguratuta. Izen irisgarri guztiak labels objektu beharrezko bakarrean datoz.

<script>
  import PickerBar from "@lilydesignsystem/svelte-picker-bar";
</script>

<PickerBar
  labels={{
    search: "Search", searchInput: "Search terms", searchSubmit: "Search",
    theme: "Theme", locale: "Language", textSize: "Text size", share: "Share",
  }}
  themesUrl="/themes/"
  locales={["en", "fr", "es"]}
  shareTargets={targets}
/>

Iritsi bildutako edozein hautatzailera honekin: searchProps, themeProps, localeProps, textSizeProps eta shareProps.

Tooltip-ak integratuta datoz

Hautatzaile bakoitzak bere etiketa tooltip batean erakusten du erakusleak bere botoian pausatzen denean edo botoiak teklatu-fokua duenean. Tooltip-a mantentzen da erakuslea gainera mugitzen denean, Escape-k baztertzen du fokua edonon dagoela, eta ez da inoiz agertzen hautatzailearen popup-a irekita dagoenean. Botoiaren izen irisgarriaren testu bera darama, beraz ez dago ezer konfiguratzeko ez bi aldiz itzultzeko; erreferentzia-gaiek estilatzen dute.

Ezarpen-panel bat leku bakarrean

Lau lehentasun-laguntzaileek modu naturalean osatzen dute:

<fieldset class="fieldset">
  <legend>Preferences</legend>
  <ThemePicker    label="Theme"     themesUrl="/themes/" themes={themes} storageKey="pref-theme" />
  <LocalePicker   label="Language"  locales={locales}    storageKey="pref-locale" />
  <TextSizePicker label="Text size" sizes={sizes}        storageKey="pref-text-size" />
  <MotionPicker   label="Motion"    motions={motions}    storageKey="pref-motion" />
</fieldset>

Non lortu

# one directory per package in the monorepo, e.g.
git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-svelte-theme-picker
# or lily-design-system-react-theme-picker, -vue- / -angular- / -html- / -web-components- / -nunjucks- / -blazor-

Pakete bakoitzak bere spec-a, spec-klausuletara mapatutako probak, exekuta daitezkeen adibideak (SSR cookie-patroiak barne) eta eraikitze + argitaratze kanalizazioa ditu. Svelte paketeak kanonikoak dira; zalantzan, haien kontratuek irabazten dute.

Hurrengo pausoak

• Osagai-katalogoa — 571 osagaien erreferentzia osoa.
• Laguntza — arazoen konponbidea eta ohiko galderak.
• Zergatik Lily — eta proiektua nola lagundu.

Galderarik bidean? laguntza-orriak erantzunez beteta dago — eta pauso bat argiagoa izan badaiteke, esan iezaguzu eta pozik hobetuko dugu tutoriala.