alif-ui 2.0.0-alpha.2 → 2.0.0-alpha.21

package/skills/alif-ui/references/patterns.md

@@ -0,0 +1,293 @@
+# alif-ui usage patterns
+
+Task-level recipes. Props for every component are in `components.md`.
+
+---
+
+## Forms
+
+alif-ui inputs are plain controlled components, so they work with `useState`, Formik and React Hook Form without adapters.
+
+### Formik
+
+```tsx
+import { useFormik } from 'formik';
+import { Input, Textarea, Button } from 'alif-ui';
+
+const form = useFormik({
+	initialValues: { email: '', about: '' },
+	onSubmit: (values) => save(values),
+});
+
+<form onSubmit={form.handleSubmit}>
+	<Input
+		label="Email"
+		name="email"
+		type="email"
+		value={form.values.email}
+		onChange={form.handleChange}
+		onBlur={form.handleBlur}
+		hasError={!!(form.touched.email && form.errors.email)}
+		hintLeftSection={form.touched.email && form.errors.email}
+	/>
+	<Button type="submit" loading={form.isSubmitting}>Submit</Button>
+</form>
+```
+
+### React Hook Form — `register()`
+
+Works for components that forward a native `ref` and emit real DOM events: `Input`, `Field`, `Textarea`, `Switch`, standalone `Checkbox` / `Radio` / `Tab`.
+
+```tsx
+<Input label="Name" {...register('name', { required: 'Name is required' })} />
+```
+
+Grouped radios/checkboxes don't need `Radio.Group` / `Checkbox.Group` with `register()` — register several standalone items under the same field name and native HTML grouping handles the rest (RHF collects same-name checkboxes into an array).
+
+### React Hook Form — `Controller`
+
+Required for the non-native controls: `Select`, `SelectMultiple`, date/time pickers, `Checkbox.Group`, `Radio.Group`, `Tab.Group`, `SegmentedControl`, `Rating`, `Slider`, `InputOtp`, `FileUploader`.
+
+```tsx
+<Controller
+	name="role"
+	control={control}
+	rules={{ validate: (value) => (value ? true : 'Select a role') }}
+	render={({ field, fieldState }) => (
+		<Select
+			label="Role"
+			options={roles}
+			{...field}
+			hasError={!!fieldState.error}
+			hintLeftSection={fieldState.error?.message}
+		/>
+	)}
+/>
+```
+
+### Validation display
+
+Error state is always the pair `hasError` + a message in `hintLeftSection` (`hintRightSection` is for counters/hints on the right). Don't render your own red text under the field, and don't use `color="danger"` for validation.
+
+---
+
+## Overlays
+
+### Confirmation modal
+
+```tsx
+const [isOpen, setIsOpen] = useState(false);
+
+<Button color="danger" onClick={() => setIsOpen(true)}>Delete</Button>
+
+<Modal isOpen={isOpen} onClose={() => setIsOpen(false)}>
+	<Modal.Header title="Delete account?" description="This action cannot be undone." />
+	<Modal.Actions>
+		<Button variant="outline" onClick={() => setIsOpen(false)}>Cancel</Button>
+		<Button color="danger" loading={isDeleting} onClick={handleDelete}>Delete</Button>
+	</Modal.Actions>
+</Modal>
+```
+
+Escape, backdrop click, scroll lock and focus trapping come with the component — don't add your own key listeners. Long content: `scrollable`. Top-aligned instead of centered: `centered={false}`.
+
+### Side panel
+
+```tsx
+<Drawer isOpen={isOpen} onClose={close} position="right" width={480} scrollable>
+	<Drawer.Header title="Filters" />
+	<Drawer.Content>…</Drawer.Content>
+	<Drawer.Actions>
+		<Button fullWidth onClick={apply}>Apply</Button>
+	</Drawer.Actions>
+</Drawer>
+```
+
+### Dropdown vs menu vs tooltip
+
+| Need | Use |
+| --- | --- |
+| Arbitrary floating content | `Popover` + `Popover.Trigger` / `Popover.Dropdown` |
+| List of actions | `Menu` with `trigger` prop and `Menu.Item` children |
+| Short hint on hover | `Tooltip` with `label` |
+| Dropdown that matches the trigger width | `Popover width="trigger"` |
+
+Inside a table row or a `position: fixed` container, pass `isFixed` so positioning is computed against the viewport.
+
+---
+
+## Lists and selection
+
+### Async select with server-side search and paging
+
+```tsx
+<Select
+	label="Client"
+	value={clientId}
+	onChange={(value) => setClientId(value)}
+	options={options}
+	filterable
+	disableClientFilter          // server does the filtering
+	onSearch={(query) => setQuery(query)}
+	loading={isLoading}          // initial load → skeletons
+	loadingMore={isFetchingNext} // paging → footer loader
+	hasMore={hasNextPage}
+	onLoadMore={fetchNextPage}
+	maxHeight={320}
+	customEmptyText="Ничего не найдено"
+/>
+```
+
+`onChange` receives `(value, option)` — take the second argument when you need the whole option (label, `secondaryText`, custom fields).
+
+### Multi-select
+
+```tsx
+<SelectMultiple values={tagIds} onChange={(values) => setTagIds(values)}
+	options={tagOptions} closeOnSelect={false} />
+```
+
+### Standalone list
+
+```tsx
+<List maxHeight={400} loading={isLoading} skeletonCount={6}
+	onLoadMore={fetchNext} hasMore={hasNextPage} loadingMore={isFetchingNext}>
+	{items.map((item) => (
+		<List.Item key={item.id} value={item.id} label={item.title}
+			secondaryText={item.subtitle} rightSection={<Badge color="success">Active</Badge>}
+			onClick={(id) => navigate(`/items/${id}`)} />
+	))}
+</List>
+```
+
+### Segmented switches — which one
+
+| Case | Component |
+| --- | --- |
+| Page sections with content panels | `Tabs` (+ `Tabs.Menu` / `Tabs.Panel`) |
+| Filter chips, single or multiple choice | `Tab.Group` with `Tab` children |
+| Compact two-to-four option switch, data-driven | `SegmentedControl` with `data` |
+
+---
+
+## Table with pagination
+
+```tsx
+<Paper variant="surface-1" radius="apple">
+	<Table highlightOnHover verticalSpacing="m" stickyHeader>
+		<Table.Thead>
+			<Table.Tr>
+				<Table.Th>Name</Table.Th>
+				<Table.Th>Status</Table.Th>
+				<Table.Th />
+			</Table.Tr>
+		</Table.Thead>
+		<Table.Tbody>
+			{rows.map((row) => (
+				<Table.Tr key={row.id}>
+					<Table.Td>{row.name}</Table.Td>
+					<Table.Td><Badge variant="light" color={row.isActive ? 'success' : 'neutral'}>{row.status}</Badge></Table.Td>
+					<Table.Td>
+						<Menu trigger={<Button variant="ghost" size="s"><OutlineSystemMoreVertical /></Button>} position="bottom-end" isFixed>
+							<Menu.Item onClick={() => edit(row)}>Edit</Menu.Item>
+							<Menu.Item onClick={() => remove(row)}>Delete</Menu.Item>
+						</Menu>
+					</Table.Td>
+				</Table.Tr>
+			))}
+		</Table.Tbody>
+	</Table>
+</Paper>
+
+<Pagination page={page} totalPages={totalPages} onPageChange={setPage}
+	itemsPerPage={perPage} itemsPerPageOptions={[{ value: 10, label: '10' }, { value: 25, label: '25' }]}
+	onItemsPerPageChange={setPerPage} />
+```
+
+Loading state: render `Skeleton` cells inside `Table.Td`, not a spinner replacing the table. Expandable rows: `Table.CollapseRow` with `isOpen` and `colSpan`.
+
+---
+
+## Notifications
+
+```tsx
+// app root, once
+<Snackbar position="top-right" />
+
+// in handlers
+try {
+	await api.save(payload);
+	snackbar.success('Изменения сохранены');
+} catch (error) {
+	snackbar.error('Не удалось сохранить', { description: getMessage(error) });
+}
+
+// or let it track the promise
+snackbar.promise(api.save(payload), {
+	loading: 'Сохраняем…',
+	success: 'Сохранено',
+	error: (err) => getMessage(err),
+});
+```
+
+Use `Alert` instead when the message belongs **inside** the page (form-level errors, banners) rather than floating over it.
+
+---
+
+## Layout shell
+
+```tsx
+<AppLayout
+	navbar={<Navbar variant="with-border"><Breadcrumbs links={crumbs} linkComponent={Link} linkProps={(to) => ({ to })} /></Navbar>}
+	sidebar={
+		<Sidebar size="large" withControlButton>
+			<Sidebar.Header logo={{ default: <AlifLogo />, compact: <AlifIcon /> }} />
+			<Sidebar.Items>
+				<Sidebar.Item icon={<OutlineSystemHome />} path="/" active={pathname === '/'}
+					linkComponent={Link} linkProps={(to) => ({ to })}>Home</Sidebar.Item>
+				<Sidebar.Collapse label="Reports" icon={<OutlineFinanceAnalytics />}>
+					<Sidebar.Item path="/reports/daily">Daily</Sidebar.Item>
+				</Sidebar.Collapse>
+			</Sidebar.Items>
+			<Sidebar.Footer>
+				<Sidebar.Profile name={user.name} subtitle={user.email} avatar={<Avatar name={user.name} />} />
+			</Sidebar.Footer>
+		</Sidebar>
+	}
+>
+	{children}
+</AppLayout>
+```
+
+`Sidebar.Item` and `Breadcrumbs` are router-agnostic: pass your router's link component via `linkComponent` + `linkProps`, or handle `onClick(path)` yourself.
+
+---
+
+## Dates
+
+```tsx
+const [date, setDate] = useState<Date | null>(null);
+<InputDatePicker label="Дата рождения" value={date} onChange={setDate} maxDate={new Date()} />
+
+const [range, setRange] = useState<[Date, Date] | null>(null);
+<InputDatePicker label="Период" isRange value={range} onChange={setRange}
+	options={[{ text: 'Последние 7 дней', value: [subDays(new Date(), 7), new Date()] }]} />
+
+<InputTimePicker label="Время" value={time} onChange={setTime} minutesStep={15} />
+```
+
+`isRange` switches the value to a `[Date, Date]` tuple and forbids `withTime`. Use the bare `DatePicker`/`TimePicker` only for a calendar rendered inline (inside a `Popover` you control, a sidebar filter, etc.).
+
+---
+
+## Responsive and progressive disclosure
+
+```tsx
+const isMobile = useMediaQuery('(max-width: 768px)');
+
+return isMobile
+	? <Drawer isOpen={isOpen} onClose={close} position="bottom">…</Drawer>
+	: <Modal isOpen={isOpen} onClose={close}>…</Modal>;
+```
+
+`Modal` also has `device="mobile"` for phone-shaped sizing. For show/hide of in-page blocks use `Collapse` (height animation) or `Transition` (any enter/exit animation).

package/skills/alif-ui/references/pitfalls.md

@@ -0,0 +1,168 @@
+# alif-ui pitfalls — wrong ↔ right
+
+These are the mistakes that actually break alif-ui code, mostly because the library's API differs from what other React UI kits do. Scan this before finishing any task that touches alif-ui.
+
+## Imports & setup
+
+```diff
+- import Button from 'alif-ui';                       // no default export
+- import { Button } from 'alif-ui/dist/main';         // no submodule paths
+- import { Button } from 'alif-ui/Button';
++ import { Button } from 'alif-ui';
+
+- // missing styles → components render unstyled
++ import 'alif-ui/styles.css';   // once, before the brand css
+
+- <AlifProvider>                                       // brand left at 'universal'
++ <AlifProvider brand="alif" initialMode="light" initialLocale="ru">
+```
+
+In Next.js, `AlifProvider` must live in a `'use client'` component. Rendering any alif-ui component **outside** the provider leaves tokens unresolved — including in tests, where the render helper must wrap the tree too.
+
+## Prop naming
+
+```diff
+- <Modal open={isOpen} onOpenChange={setIsOpen}>
++ <Modal isOpen={isOpen} onClose={() => setIsOpen(false)}>
+
+- <Popover open onOpenChange={…}>
++ <Popover isOpen onChange={(isOpen) => …}>
+
+- <Badge notifications={10} />
++ <Indicator label={10}><Avatar name="J" /></Indicator>
+```
+
+Booleans are `is*` / `with*` / `keep*` / `show*`; handlers are `on*`. There is no `onOpenChange` anywhere in the library.
+
+## Composition
+
+```diff
+- <Table><thead><tr><th>Name</th></tr></thead></Table>
++ <Table><Table.Thead><Table.Tr><Table.Th>Name</Table.Th></Table.Tr></Table.Thead></Table>
+
+- import { ModalHeader } from 'alif-ui';       // sub-parts are not separate exports
++ <Modal.Header title="…" />
+
+- <Popover><Button>Open</Button><div>content</div></Popover>
++ <Popover>
++   <Popover.Trigger><Button>Open</Button></Popover.Trigger>
++   <Popover.Dropdown>content</Popover.Dropdown>
++ </Popover>
+
+- <Menu><Menu.Trigger>…</Menu.Trigger>…</Menu>   // Menu has no Trigger part
++ <Menu trigger={<Button>Actions</Button>}><Menu.Item>…</Menu.Item></Menu>
+
+- <Tooltip><Button/><span>hint</span></Tooltip>
++ <Tooltip label="hint"><Button /></Tooltip>
+```
+
+## Controlled state
+
+```diff
+- <Tabs defaultValue="profile">                 // Tabs is controlled-only
++ <Tabs value={tab} onChange={setTab}>
+
+- <Select value={role} onChange={setRole} />    // onChange has two arguments
++ <Select value={role} onChange={(value, option) => setRole(value)} />
+
+- <SelectMultiple value={ids} onChange={setIds} />
++ <SelectMultiple values={ids} onChange={setIds} />
+
+- <Accordion type="multiple" value="a">         // multiple → arrays
++ <Accordion type="multiple" value={['a']} onChange={(values) => …} />
+```
+
+`Select`, `Rating`, `InputOtp`, `FileUploader`, `Slider`, `Pagination`, `SegmentedControl` and the date pickers **require** their value/handler pair — there is no uncontrolled fallback. `Accordion`, `Popover`, `Tab.Group`, `Checkbox.Group`, `Radio.Group`, `List.Group` accept `defaultValue`/`defaultOpen`.
+
+## Styling
+
+```diff
+- <Button style={{ backgroundColor: '#0046fd', borderRadius: 8, fontSize: 14 }}>
++ <Button variant="main" color="highlight" size="s">
+
+- .myButton { background: #fff !important; }
++ .myButton { --button-main-bg-color-primary-default: var(--brand-bg-surface-1); }
+
+- <div className="Button-module__root__a1b2">   // hashed, changes every build
++ <Button className={styles.myButton} />
+
+- <div style={{ color: 'var(--solid-neutral-0)' }}>   // primitive: breaks dark mode
++ <div style={{ color: 'var(--mode-text-default)' }}>
+
+- @media (prefers-color-scheme: dark) { … }
++ /* nothing needed — tokens switch via <html data-theme> */
+
+- <div style={{ width: '100%' }}><Button /></div>
++ <Button fullWidth />
+```
+
+Also: don't wrap a component just to add margin — put spacing on your own layout container; and don't re-implement a component's states (hover/disabled/loading), they are built in (`loading`, `disabled`).
+
+## Wrong component for the job
+
+| Symptom | Instead |
+| --- | --- |
+| Hand-written `<div>` card with shadow and radius | `Paper` |
+| Styled `<h2>` / `<p>` | `Typography` with `variant` + `size` |
+| Custom spinner or "Loading…" text | `Loader`, or `Skeleton` for content placeholders |
+| `<div onClick>` | `UnstyledButton` (or `Button`) |
+| Own toast/notification stack | `<Snackbar />` + `snackbar.*` |
+| Inline error text under an input | `hasError` + `hintLeftSection` |
+| Own dropdown positioning logic | `Popover` / `Menu` / `Select` |
+| Own modal with `createPortal` + Escape handling | `Modal` / `Drawer` |
+| `<select>` or a third-party select | `Select` / `SelectMultiple` |
+| Page tabs built from buttons + conditional render | `Tabs` + `Tabs.Panel` |
+| Filter chips built from `Tabs` | `Tab.Group` or `SegmentedControl` |
+| Toast for a form-level error banner | `Alert` |
+
+## Sizes and scales
+
+```diff
+- <Avatar size="m" />  ✔   <List size="s" />  ✘  (List is 'm' | 'l')
+- <Input size="xs" />  ✘  (Input/Field/Textarea are 's' | 'm' | 'l')
+- <Button size="xl" /> ✘  (Button is 'xs' | 's' | 'm' | 'l')
+- <Checkbox size="l" /> ✘ (Checkbox/Radio/Switch are 's' | 'm')
+```
+
+Only `Typography`, `Badge`, `Indicator`, `Paper`, `Sidebar`, `ProgressBar` and `Loader` accept a free-form `color`; everywhere else it is a fixed union — a hex will be ignored or rejected by TypeScript. Even where a string is allowed, pass a token (`var(--brand-content-accent)`), not a literal color.
+
+## Forms
+
+```diff
+- <Select {...register('role')} />              // non-native control
++ <Controller name="role" control={control} render={({ field }) => <Select {...field} options={roles} />} />
+```
+
+`register()` is only for components that forward a native ref and fire DOM events: `Input`, `Field`, `Textarea`, `Switch`, standalone `Checkbox` / `Radio` / `Tab`. Everything else needs `Controller` (or manual `value`/`onChange`).
+
+## Overlays inside scroll containers
+
+A `Popover`/`Menu`/`Select` inside a `position: fixed` container or a scrolling table needs `isFixed` so its dropdown is positioned against the viewport. Nested popovers are supported — don't build your own nesting logic.
+
+## Icons
+
+```diff
+- <img src="/icons/settings.svg" />
+- <svg>…</svg>
++ <SolidSystemSettings />
+
+- <SolidSystemSettings fill="#000" width="18" />
++ <SolidSystemSettings />        // inherits currentColor and the component's icon size
+```
+
+Names are `Outline*`/`Solid*` + category + name (`OutlineSystemSearch`, `OutlineNavigationChevronDown`, `OutlineFinanceAccounts`); flags are `<Cc>Flag`. If unsure a name exists, check `node_modules/alif-ui/dist/main.d.ts` rather than guessing — a wrong name is a build error.
+
+## Localization
+
+```diff
+- const { t } = useTranslation();  // without localization.init(loader) → keys returned as-is
++ await localization.init((locale) => fetch(`/locales/${locale}.json`).then((r) => r.json()));
+
+- changeLanguage('en');            // async
++ await changeLanguage('en');
+
+- t(`Привет, ${name}!`)
++ t('greeting', { name })          // "Привет, {{name}}!"
+```
+
+Hardcoding user-visible strings inside components is fine only in apps that don't use i18n — if the project has `locales/*.json`, route copy through `t()`.

package/skills/alif-ui/references/theming.md

@@ -0,0 +1,125 @@
+# Theming, tokens, i18n
+
+## How theming works
+
+Three attributes on `<html>`, all managed by `AlifProvider`:
+
+| Attribute | Values | Set by |
+| --- | --- | --- |
+| `data-brand` | `universal` (built in) or the project's own brand name | `brand` prop |
+| `data-theme` | `light`, `dark` | `initialMode` / `useMode().toggleMode()` (`system` resolves to one of the two) |
+| `data-locale` | `ru`, `en`, `tj` | `initialLocale` / `useLocale().setLocale()` |
+
+Tokens cascade: **primitive** (`--solid-*`, `--tint-*`) → **mode** (`--mode-*`, swapped by `data-theme`) → **brand** (`--brand-*`, swapped by `data-brand`) → **component** (`--button-*`, `--progress-bar-*`, …).
+
+Application code should use the **`--brand-*` layer** (or `--mode-*` when no brand token fits). Never use a primitive (`--solid-blue-500`) and never a literal color — both break dark mode and brand switching.
+
+## Tokens you will actually use
+
+**Text** — `--mode-text-default`, `-secondary`, `-tertiary`, `-accent`, `-link`, `-success`, `-danger`, `-error`, `-always-white`, `-always-black`.
+
+**Backgrounds** — `--brand-bg-page-primary` / `-secondary` / `-tertiary`, `--brand-bg-surface-1` / `-2` / `-3`, `--brand-bg-elevated`, `--brand-bg-accent`, `--brand-bg-success` / `-warning` / `-danger` (each with `-tint-10` / `-20` / `-40` for soft fills).
+
+**Borders** — `--brand-border-color-default`, `-secondary`, `-tertiary`, `-accent`, `-success`, `-danger`, `-error`, `-link`.
+
+**Content/icon colors on surfaces** — `--brand-content-default`, `-secondary`, `-tertiary`, `-accent`, `-success`, `-danger`, `-error`, `-link`, `-always-white`, `-always-black`.
+
+**Brand accent** — `--brand-default`, `--brand-hover`, `--brand-active`, `--brand-pale`, `--brand-tint-5/10/20/40`, and the `--brand-highlight-*` set.
+
+**Radii** — `--brand-border-radius-none | cherry | strawberry | strawberry-alt | apricot | dulona | peach | apple | coconut | grapefruit | pomelo | blackberry | full` (fruit names are the design system's size scale, smallest → largest).
+
+**Control heights** — `--brand-size-controls-100 | 150 | 200 | 350 | 500 | 600`.
+
+**Typography** — `--brand-font-family-{body|heading|display|description}`, `--brand-font-size-*`, `--brand-font-line-height-*`, `--brand-font-letter-spacing-*`, `--brand-font-weight-{thin…black}`. Prefer the `Typography` component over using these directly.
+
+**Shadows** — `--shadow-xs | s | m | l | xl`. **Durations** — `--duration-instant | very-fast | fast | normal | slow | slower`.
+
+## Styling around components
+
+Order of preference:
+
+1. **Props.** `variant`, `color`, `size`, `fullWidth`, `radius`, `shadow`, `bgColor` cover most of the design system.
+2. **Layout via your own wrapper.** Put margins, grid and flex on your container, not on the library component.
+3. **`className` / `style`.** Both are forwarded to the root element and merged after the component's own styles.
+4. **Component CSS variables.** Every component declares its theming surface as custom properties on its root, so overriding one variable is safe and survives library updates:
+
+```css
+/* your app's css */
+.dangerButton {
+  --button-main-bg-color-primary-default: var(--brand-bg-danger);
+  --button-main-bg-color-primary-hover: var(--mode-solid-red-600);
+}
+```
+
+```tsx
+<Button className={styles.dangerButton}>Delete</Button>
+```
+
+The variable names follow `--<component>-<variant>-<property>-<color>-<state>`. To find the exact one, inspect the element in devtools — the root element lists them all.
+
+**Never**: target the library's generated class names (`.Button-module__root__x1y2z`) — they are hashed and change between builds; use `!important` to fight the design system; or copy a component's CSS into your project.
+
+## Dark mode
+
+```tsx
+const { mode, toggleMode } = useMode();
+
+<Button variant="ghost" onClick={toggleMode}>
+	{mode === 'dark' ? <SolidSystemSun /> : <SolidSystemMoon />}
+</Button>
+```
+
+Every token has a light and a dark value, so components adapt automatically. Your own CSS must use tokens for the same reason — a hardcoded `#fff` background turns unreadable in dark mode. Do not write `@media (prefers-color-scheme: dark)` blocks; the `data-theme` attribute is the source of truth. During a theme flip the library adds `.themeChanging` to `<html>` for one frame to suppress transitions.
+
+## Brands
+
+`universal` is the only brand bundled in the package, and it is the fallback when no other is set. A real project gets its own brand CSS from the design team: one file that redefines the `--brand-*` layer under its own selector.
+
+```css
+/* styles/alif/alif.css — supplied by the design team */
+:root[data-brand='alif'] {
+  --brand-default: var(--mode-solid-green-500);
+  /* … the rest of the --brand-* layer */
+}
+```
+
+```tsx
+import 'alif-ui/styles.css';   // brings the universal brand
+import 'styles/alif/alif.css'; // overrides it for data-brand='alif'
+
+<AlifProvider brand="alif">{children}</AlifProvider>
+```
+
+Rules: import **exactly one** brand file, right after `alif-ui/styles.css`, and pass the name from its `[data-brand='…']` selector to the `brand` prop. A mismatch is silent — the attribute is set, no selector matches, and the app keeps the universal look. Everything else adapts on its own; there is no per-component brand prop.
+
+## Localization
+
+Optional; the library ships no user-facing copy, but it can host your app's translations.
+
+```tsx
+// entry point, before render
+import { localization } from 'alif-ui';
+
+await localization.init((locale) => fetch(`/locales/${locale}.json`).then((r) => r.json()));
+```
+
+Translation files live wherever your loader points (commonly `public/locales/{ru,en,tj}.json`).
+
+```tsx
+const { t, language, changeLanguage } = useTranslation();
+
+t('greeting');                       // "Hello!"
+t('greeting', { name: 'Alif' });     // fills {{name}} / {{ name }}
+t('snackbar.title');                 // nested keys use dot notation
+await changeLanguage('en');          // async — fetches the locale file
+```
+
+A missing key (or one whose value isn't a string) is returned verbatim, so untranslated UI shows the key itself — useful for spotting gaps.
+
+Outside React (event handlers, API layers, utils) use `localization.t('key', params?)` — same interpolation. Placeholders you don't pass are left as-is rather than becoming `undefined`.
+
+`useLocale()` (`{ locale, setLocale }`) changes the `data-locale` attribute and the persisted preference; `changeLanguage` from `useTranslation` additionally loads the translation file. If the app uses the built-in i18n, prefer `changeLanguage`.
+
+## Global helper classes
+
+Available from `alif-ui/styles.css`: `uiFullWidth` (`width: 100%`), `hideScrollbar`, and `uiFont` (applies the `--typography-*` variables — used internally by components; in app code use `Typography` instead).

package/dist/Accordion.module-DKzAMqjv.js

@@ -1,13 +0,0 @@
-const c = "_root_1caww_1", t = "_item_1caww_13", o = "_withDivider_1caww_18", n = "_trigger_1caww_22", e = "_triggerIcon_1caww_37", r = "_chevron_1caww_43", _ = "_chevronOpen_1caww_47", w = "_content_1caww_51", i = {
-  root: c,
-  item: t,
-  withDivider: o,
-  trigger: n,
-  triggerIcon: e,
-  chevron: r,
-  chevronOpen: _,
-  content: w
-};
-export {
-  i as c
-};

package/dist/BackdropOverlay-DTdSMHF5.js

@@ -1,11 +0,0 @@
-import { jsx as o } from "react/jsx-runtime";
-import { classNames as t } from "./utils/class-names.js";
-import { Transition as a } from "./components/Transition/Transition.js";
-const e = "_root_13p6u_1", n = "_overlay_13p6u_9", c = {
-  root: e,
-  overlay: n
-}, p = ({ isOpen: r }) => /* @__PURE__ */ o(a, { mounted: r, transition: "fade", duration: 300, children: (s) => /* @__PURE__ */ o("div", { style: s, className: t(c.overlay) }) });
-export {
-  p as B,
-  c
-};

package/dist/Dates.module-DMolkD_T.js

@@ -1,38 +0,0 @@
-const e = "_root_x12kc_1", n = "_dateTimeContainer_x12kc_53", t = "_calendarContainer_x12kc_58", o = "_controlPanel_x12kc_62", c = "_controlPanelButtonArrow_x12kc_70", a = "_controlPanelDateContainer_x12kc_85", _ = "_controlPanelButtons_x12kc_90", r = "_controlPanelActiveButtons_x12kc_105", i = "_calendar_x12kc_58", l = "_calendarShadow_x12kc_117", d = "_dateCell_x12kc_128", k = "_today_x12kc_146", s = "_active_x12kc_151", m = "_rangeMiddle_x12kc_151", x = "_rangeStart_x12kc_151", P = "_rangeEnd_x12kc_151", C = "_confirmationBlock_x12kc_166", g = "_dateOptions_x12kc_175", u = "_weekend_x12kc_183", w = "_todayRangeMiddle_x12kc_226", y = "_month_x12kc_230", B = "_inlineTimePickerWrapper_x12kc_234", v = "_timePicker_x12kc_239", p = "_timePickerColumn_x12kc_247", M = "_time_x12kc_239", T = "_timeHeaderContainer_x12kc_270", f = "_timeHeader_x12kc_270", h = "_activeTime_x12kc_286", A = "_timeOverlay_x12kc_290", H = "_confirmationButton_x12kc_301", O = "_days_x12kc_305", R = "_weekday_x12kc_312", S = "_weekendRangeMiddle_x12kc_317", D = {
-  root: e,
-  dateTimeContainer: n,
-  calendarContainer: t,
-  controlPanel: o,
-  controlPanelButtonArrow: c,
-  controlPanelDateContainer: a,
-  controlPanelButtons: _,
-  controlPanelActiveButtons: r,
-  calendar: i,
-  calendarShadow: l,
-  dateCell: d,
-  today: k,
-  active: s,
-  rangeMiddle: m,
-  rangeStart: x,
-  rangeEnd: P,
-  confirmationBlock: C,
-  dateOptions: g,
-  weekend: u,
-  todayRangeMiddle: w,
-  month: y,
-  inlineTimePickerWrapper: B,
-  timePicker: v,
-  timePickerColumn: p,
-  time: M,
-  timeHeaderContainer: T,
-  timeHeader: f,
-  activeTime: h,
-  timeOverlay: A,
-  confirmationButton: H,
-  days: O,
-  weekday: R,
-  weekendRangeMiddle: S
-};
-export {
-  D as c
-};

package/dist/Drawer.module-Bxp60Xmp.js

@@ -1,18 +0,0 @@
-const t = "_root_1vrnm_1", o = "_right_1vrnm_21", n = "_left_1vrnm_25", _ = "_top_1vrnm_29", r = "_bottom_1vrnm_33", e = "_rounded_1vrnm_37", c = "_drawer_1vrnm_41", s = "_header_1vrnm_55", l = "_title_1vrnm_62", m = "_description_1vrnm_67", d = "_content_1vrnm_72", v = "_scrollable_1vrnm_77", i = "_closeButton_1vrnm_86", a = {
-  root: t,
-  right: o,
-  left: n,
-  top: _,
-  bottom: r,
-  rounded: e,
-  drawer: c,
-  header: s,
-  title: l,
-  description: m,
-  content: d,
-  scrollable: v,
-  closeButton: i
-};
-export {
-  a as c
-};