rei-kit 2.19.0 → 2.21.0

package/README.md

@@ -1,6 +1,6 @@
 # rei-kit
 
-**One kit. Every look.** 96 accessible components for Vue 3 and Tailwind 4.
+**One kit. Every look.** 99 accessible components for Vue 3 and Tailwind 4.
 Change the **material** with one attribute and the **palette** with another —
 every component follows, and none of them knows your brand.
 
@@ -112,7 +112,7 @@ Each claim here is enforced by something that fails, not by a promise.
 
 | Standard                                 | How it is held                                                                                                                                                                                                                                                                                                                          |
 | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Open for extension, closed for edits** | A new look is a token, a material or a palette — never an edit to a component. Materials and palettes restyle all 96 without touching one, and a test fails if a component holds a colour.                                                                                                                                              |
+| **Open for extension, closed for edits** | A new look is a token, a material or a palette — never an edit to a component. Materials and palettes restyle all 99 without touching one, and a test fails if a component holds a colour.                                                                                                                                              |
 | **Single responsibility**                | One part, one job. Label-and-error wiring lives in `FormField`, not in five inputs; taking the page behind a layer out of reach lives in one helper the modal, the sheet and the guide share.                                                                                                                                           |
 | **Depend on roles, not values**          | Components read `primary`, `surface`, `--shadow-card` — never a hex or a pixel shadow. An app's brand wins in both modes, tested.                                                                                                                                                                                                       |
 | **WAI-ARIA Authoring Practices**         | Menus, comboboxes, tabs, sliders, dialogs and accordions follow their APG pattern: arrows move, Tab leaves, Escape closes, focus returns. Behaviour tests drive each with the keyboard.                                                                                                                                                 |
@@ -128,7 +128,7 @@ Each claim here is enforced by something that fails, not by a promise.
 
 |              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Components   | 96 (`AuthForm`, `BaseTable`, `BaseCombobox`, `BaseSlider`, `TabShell`, `BaseModal`, `BaseTabs`, `BaseTooltip`, `BasePagination`, `BaseBreadcrumb`, `BaseDisclosure`, `BaseAccordion`, `NavLinks`, `OfflineBanner`, `FabButton`, `BaseButton`, `BaseCard`, `BaseInput`, `BaseSelect`, `BaseTextarea`, `BaseCheckbox`, `BaseSwitch`, `BaseRadioGroup`, `BaseMenu`, `BaseAvatar`, `BaseSpinner`, `BaseAlert`, `BaseBadge`, `BaseSheet`, `ProgressBar`, `PriceCard`, `ToastHost`, `TabBar`, `GoogleButton`, `LocaleLinks`, `LocaleSheet`, `AuthShell`, `TourShell`, `InstallPrompt`, `UpdatePrompt`, `InstallSettings`, `SkeletonList`, `PageContainer`, `ErrorBoundary`, etc.) |
+| Components   | 99 (`AuthForm`, `BaseTable`, `BaseCombobox`, `BaseSlider`, `TabShell`, `BaseModal`, `BaseTabs`, `BaseTooltip`, `BasePagination`, `BaseBreadcrumb`, `BaseDisclosure`, `BaseAccordion`, `NavLinks`, `OfflineBanner`, `FabButton`, `BaseButton`, `BaseCard`, `BaseInput`, `BaseSelect`, `BaseTextarea`, `BaseCheckbox`, `BaseSwitch`, `BaseRadioGroup`, `BaseMenu`, `BaseAvatar`, `BaseSpinner`, `BaseAlert`, `BaseBadge`, `BaseSheet`, `ProgressBar`, `PriceCard`, `ToastHost`, `TabBar`, `GoogleButton`, `LocaleLinks`, `LocaleSheet`, `AuthShell`, `TourShell`, `InstallPrompt`, `UpdatePrompt`, `InstallSettings`, `SkeletonList`, `PageContainer`, `ErrorBoundary`, etc.) |
 | Composables  | 16 (`useToast`, `useTheme`, `useMaterial`, `usePalette`, `useToday`, `useMediaQuery`, `useInstall`, `watchInstallability`, `createTabTransition`, `useThemeSync`, `useVisualViewport`, etc.)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | Utilities    | 33 (`applyTheme`, `applyMaterial`, `applyPalette`, `MATERIALS`, `PALETTES`, `formatDate`, `fieldErrors`, `toAuthMessageKey`, `createAuthGuard`, `createQueryDefaults`, `createWriteReport`, `toRedirectPath`, `Supabase error mapper`, i18n runtime, etc.)                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | Entry Points | `rei-kit`, `rei-kit/app`, `rei-kit/web`, `rei-kit/pwa`, `rei-kit/supabase`, `rei-kit/mobile.css`, `rei-kit/web.css`, and each stylesheet on its own                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

package/dist/components/ActivityGrid.vue.d.ts

@@ -0,0 +1,52 @@
+import { WeekStart } from '../utils/date';
+/**
+ * A year of days, as a grid you can read at a glance.
+ *
+ * ## It is a table, and that is not a detail
+ *
+ * Weekdays are the rows and weeks are the columns, so the markup is a
+ * `<table>` and the visual layout falls out of it. The obvious way — one
+ * CSS grid flowing column by column — puts the DOM in a different order
+ * from the picture, and anything laid over that order afterwards
+ * (`role="grid"`, arrow keys, a reader's own table navigation) then
+ * describes a shape that is not on screen.
+ *
+ * ## One stop, not three hundred and sixty-five
+ *
+ * Every day is reachable, and the whole grid is a single stop in the tab
+ * order: the arrows move between days, Home and End go to the ends of a
+ * week, and Enter chooses. A grid of focusable cells is the other way this
+ * is written, and it costs somebody using a keyboard a year of presses to
+ * get past a picture.
+ *
+ * ## The colours are yours
+ *
+ * `levelFor` returns a class, the same contract as `ToneDot`'s `fill` and
+ * `BaseTimeline`'s: the kit does not know whether four of something is a
+ * lot, or which hue your product uses for "done". `dayLabel` is the same
+ * for words — the kit has no language, and a date reads differently in
+ * every one.
+ */
+type __VLS_Props = {
+    /** The days to draw, as `YYYY-MM-DD`, oldest first. */
+    days: readonly string[];
+    /** Names the grid, e.g. "Your year". Already translated. */
+    label: string;
+    /** A class for one day's square, e.g. `bg-positive/40`. */
+    levelFor: (key: string) => string;
+    /** What a reader hears on a day: the date, and what happened. Translated. */
+    dayLabel: (key: string) => string;
+    /** Which days lead somewhere. Unset, the grid is a picture and nothing else. */
+    isSelectable?: ((key: string) => boolean) | undefined;
+    /** `1` Monday, `0` Sunday. */
+    weekStartsOn?: WeekStart | undefined;
+    /** Open on the most recent weeks — a year otherwise starts far off-screen. */
+    startAtEnd?: boolean | undefined;
+};
+declare const __VLS_export: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    select: (key: string) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onSelect?: (key: string) => any;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/ScrollArea.vue.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A box that scrolls, with the two things a hand-written one leaves out.
+ *
+ * ## The edge fade is the affordance `no-scrollbar` takes away
+ *
+ * Every app here hides the scrollbar on a horizontal row — a strip of
+ * months, a row of filter chips — because a native bar under a 40px row is
+ * louder than the row. What goes with it is the only sign on screen that
+ * there is anything further along. So the fades are driven by the actual
+ * scroll position: one appears at an edge exactly when there is content
+ * past it, and both are gone when everything fits.
+ *
+ * ## A focus stop, but only when there is no other way in
+ *
+ * A box that scrolls and cannot take focus cannot be scrolled by a
+ * keyboard, so the far end is simply unreachable. That is the fault
+ * `CodeBlock` was written for, and it is not about code: it is true of any
+ * scrolling box whose contents are not focusable.
+ *
+ * But it is *only* true of those. A row of buttons already moves under the
+ * keyboard — Tab scrolls the next one into view — and giving that row a
+ * stop of its own costs a press for nothing, on every row. So this checks:
+ * it becomes a named region when it overflows **and** holds nothing
+ * focusable, and stays out of the tab order otherwise.
+ *
+ * The check runs when the box or its contents resize, which covers a list
+ * that arrives from a server. A swap that changes neither size — the same
+ * number of rows, buttons turned into plain text — will not be noticed;
+ * that is a trade against watching every mutation of a scroll container,
+ * and the shape it misses is a rare one.
+ */
+type __VLS_Props = {
+    /**
+     * Names the box, e.g. "Categories".
+     *
+     * Required because this becomes a region a reader can land in, and an
+     * unnamed region is announced as nothing at all. It is only used when
+     * that happens, so it costs nothing in the common case.
+     */
+    label: string;
+    /** Which way it scrolls. */
+    axis?: 'x' | 'y' | 'both' | undefined;
+    /** `hidden` takes the native bar away; the fades stay either way. */
+    scrollbar?: 'auto' | 'hidden' | undefined;
+    /** The gradient at an edge with more content past it. */
+    fade?: boolean | undefined;
+    /** Drag to scroll sideways, for a page that has claimed horizontal gestures. */
+    drag?: boolean | undefined;
+};
+type __VLS_Slots = {
+    default: () => unknown;
+};
+declare const __VLS_base: import('vue').DefineComponent<__VLS_Props, {
+    /** The element that actually scrolls, for a parent that has to measure it. */
+    viewport: Readonly<import('vue').ShallowRef<HTMLElement | null>>;
+}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    scroll: (event: Event) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onScroll?: (event: Event) => any;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/VirtualList.vue.d.ts

@@ -0,0 +1,37 @@
+declare const __VLS_export: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: import('vue').PublicProps & __VLS_PrettifyLocal<{
+        /** The whole list. Only the rows near the viewport are rendered. */
+        items: readonly T[];
+        /** Every row is this tall, in pixels. */
+        rowHeight: number;
+        /** Names the list, e.g. "Bütün kayıtlar". Already translated. */
+        label: string;
+        /** Below this many rows the list is not windowed at all. */
+        virtualizeAfter?: number | undefined;
+        /** Passed to the scroll area: `hidden` takes the native bar away. */
+        scrollbar?: "auto" | "hidden" | undefined;
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: import('vue').ShallowUnwrapRef<{
+        scrollToIndex: (index: number) => void;
+    }>) => void;
+    attrs: any;
+    slots: {
+        /** One row. `index` is its place in the whole list, not in the window. */
+        default: (props: {
+            item: T;
+            index: number;
+        }) => unknown;
+    };
+    emit: {};
+}>) => import('vue').VNode & {
+    __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
+};
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

package/dist/composables/use-virtual-window.d.ts

@@ -0,0 +1,39 @@
+import { Ref } from 'vue';
+export interface VirtualWindowOptions {
+    /** How many rows there are in total. */
+    count: Ref<number>;
+    /** Every row is this tall, in pixels. Fixed — that is what makes the
+     *  arithmetic possible without measuring each one. */
+    rowHeight: Ref<number>;
+    /**
+     * Below this many rows the window is the whole list and the padding is
+     * zero, so a short list renders exactly as it would without any of this.
+     */
+    threshold: Ref<number>;
+}
+/**
+ * The arithmetic behind a windowed list: which rows are near the viewport,
+ * and how much empty space stands in for the rest.
+ *
+ * This is the part `BaseCombobox` and `VirtualList` share. It was written
+ * inside the combobox first, and pulling it out here is the reason there is
+ * one copy of it rather than two — the second would have drifted, and the
+ * half that drifts silently is the padding, which is what keeps the
+ * scrollbar honest about how long the list is.
+ *
+ * There is no clock and no observer in here: it is a function of the scroll
+ * position, and the component that owns the element is what tells it where
+ * that is. That is also what makes it testable without a layout.
+ */
+export declare function useVirtualWindow({ count, rowHeight, threshold }: VirtualWindowOptions): {
+    active: import('vue').ComputedRef<boolean>;
+    window: import('vue').ComputedRef<{
+        start: number;
+        end: number;
+    }>;
+    padTop: import('vue').ComputedRef<number>;
+    padBottom: import('vue').ComputedRef<number>;
+    scrollTop: Ref<number, number>;
+    viewportHeight: Ref<number, number>;
+    onScroll: (event: Event) => void;
+};

package/dist/index.d.ts

@@ -90,6 +90,23 @@ export { default as LocaleLinks } from './components/LocaleLinks.vue';
 export { default as GoogleButton } from './components/GoogleButton.vue';
 export { default as TabBar } from './components/TabBar.vue';
 export type { TabItem } from './components/TabBar.vue';
+/**
+ * `ActivityGrid`, a year at a glance — a real table, so the DOM order is
+ * the picture's order, and one tab stop rather than three hundred odd.
+ */
+export { default as ActivityGrid } from './components/ActivityGrid.vue';
+/**
+ * `ScrollArea`, a scrolling box with the two things a hand-written one
+ * leaves out: a fade at whichever edge has more content past it, and a
+ * focus stop — but only when nothing inside it can take focus.
+ */
+export { default as ScrollArea } from './components/ScrollArea.vue';
+/**
+ * `VirtualList`, a long list where only the rows near the viewport exist —
+ * and every one of them states its place in the whole, which is the half
+ * that is usually dropped.
+ */
+export { default as VirtualList } from './components/VirtualList.vue';
 export { default as AvatarStack } from './components/AvatarStack.vue';
 export { default as BaseCalendar } from './components/BaseCalendar.vue';
 export { default as BaseChip } from './components/BaseChip.vue';