rei-kit 0.7.0 → 0.8.0

package/README.md

@@ -16,17 +16,41 @@ That is the whole trick, and everything else follows from it.
 
 ### What gets to be in here
 
-Three things have to be true at once:
-
-1. **Two apps genuinely need it** — measured, not predicted. A component one
-   app needs stays in that app however general it looks.
-2. **It adds no required peer.** Anything that needs a new library goes behind
-   its own entry point, or stays in the app.
-3. **It contains no product decision** — no colour, no copy, no icon. Those
-   arrive as props and slots.
-
-The corollary is the useful one: **a file that is 90% identical in two apps is
-a kit candidate.** The measure is `diff`, not taste.
+The kit is not built from what its current apps happen to need. It is built to
+be the thing the next app starts from. So the rule depends on what kind of
+thing is being added — and conflating the two cost this package three releases
+that shipped parts nobody could use.
+
+**Primitives are complete by construction.** A button, a field, a toast, a
+modal. There is no uncertainty about whether the next app will want one, so
+they do not wait for a second consumer: waiting means every new app begins by
+copying, which is the thing this package exists to prevent. A primitive is
+finished when two checkable things are true:
+
+- **It covers every role the design system declares.** `tokens.css` names five
+  colour roles while `BaseButton` exposed two, so an app that wanted a
+  success-coloured action hand-wrote the button. A component that cannot use a
+  role its own token file declares is not being careful; it is incomplete.
+- **The app can take the behaviour without the appearance.** `variant="unstyled"`
+  exists because 58 raw `<button>` elements sat in 24 files that already
+  imported `BaseButton`. A picker cell, a chip, a calendar day: the surface is
+  the app's and should be, but the element, the focus ring, the disabled
+  handling and the `aria-pressed` bookkeeping are not — and they were being
+  rewritten every time, usually without the focus ring.
+
+**Composed components wait for two apps.** A `PriceCard`, a `TourShell`, a
+`DangerZone`. These carry a shape, and a shape designed from one example is
+designed wrong. Here the measure is `diff`, not taste: **a file that is 90%
+identical in two apps is a kit candidate.**
+
+**Both kinds:** no new required peer — anything needing a library goes behind
+its own entry point or stays in the app — and no product decision. No colour,
+no copy, no icon. Those arrive as props and slots.
+
+**And one test worth more than the rule:** a raw `<button>` in a file that
+already imports `BaseButton` is a bug in the kit, not in the app. That grep
+found every gap closed between 0.5.0 and 0.7.0, and it found them after those
+releases had claimed to be finished.
 
 ## Status
 

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

@@ -13,9 +13,9 @@ type __VLS_ModelProps = {
     modelValue: boolean;
 };
 type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
-declare var __VLS_18: {};
+declare var __VLS_26: {};
 type __VLS_Slots = {} & {
-    default?: (props: typeof __VLS_18) => any;
+    default?: (props: typeof __VLS_26) => any;
 };
 declare const __VLS_base: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
     "update:modelValue": (value: boolean) => any;

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

@@ -0,0 +1,24 @@
+/**
+ * Where the toasts land. One of these, at the app root.
+ *
+ * @example
+ * ```vue
+ * <!-- App.vue -->
+ * <ToastHost :close-label="$t('common.close')" />
+ * ```
+ */
+type __VLS_Props = {
+    /**
+     * The accessible name of each dismiss button. Required, because the button
+     * is an X and an X has no name — and the kit does not know the language.
+     */
+    closeLabel: string;
+    /**
+     * Stack from the bottom instead of the top. For a phone shell, where the top
+     * is a status bar and a header and the thumb is nowhere near it.
+     */
+    bottom?: boolean | undefined;
+};
+declare const __VLS_export: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/composables/use-toast.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Saying that something happened.
+ *
+ * The reason this exists is a measurement rather than a preference: the word
+ * "toast" appeared **zero times** across all three consuming apps. Not because
+ * they had decided against it — because there was no mechanism, so every save,
+ * every delete and every export finished in silence and the only way to know
+ * it had worked was that nothing had visibly broken.
+ *
+ * ── What is deliberately not here ──
+ *
+ * **No text.** The kit never knows a sentence. Callers pass the message; a
+ * component that called a translator would force one on the app.
+ *
+ * **Not for form errors.** A field that was rejected says so beside itself,
+ * where the reader's eye already is and where it stays until fixed. A toast
+ * that disappears after four seconds is the wrong place for something the
+ * reader has to act on. Use `BaseAlert` and `FormField` for those; use this
+ * for what has already happened.
+ *
+ * **A singleton, on purpose.** Two hosts would mean two stacks racing for the
+ * same corner. The store lives at module scope and `ToastHost` renders it.
+ */
+export type ToastTone = 'info' | 'success' | 'warning' | 'danger';
+export interface Toast {
+    readonly id: number;
+    readonly message: string;
+    readonly tone: ToastTone;
+    /** Milliseconds on screen. `0` stays until dismissed. */
+    readonly duration: number;
+}
+export interface ToastOptions {
+    /** Milliseconds on screen; `0` stays until dismissed. */
+    duration?: number | undefined;
+}
+/** Removes a toast, whether it timed out or was dismissed. */
+declare function dismiss(id: number): void;
+/** Removes everything on screen. For a route change, or a sign-out. */
+declare function dismissAll(): void;
+/**
+ * Stops the clock on a toast the reader is pointing at.
+ *
+ * Somebody who has moved the pointer onto it is reading it, and taking it away
+ * mid-sentence is the one thing a notification must not do.
+ */
+declare function pause(id: number): void;
+/** Starts it again, from where it stopped rather than from the beginning. */
+declare function resume(id: number): void;
+/**
+ * The stack, and the four ways to add to it.
+ *
+ * @example
+ * ```ts
+ * const toast = useToast()
+ *
+ * toast.success(t('habit.saved'))
+ * toast.danger(t('common.failed'), { duration: 0 })  // stays until dismissed
+ *
+ * const id = toast.info(t('export.preparing'), { duration: 0 })
+ * toast.dismiss(id)
+ * ```
+ */
+export declare function useToast(): {
+    /** Every toast on screen, oldest first. `ToastHost` renders this. */
+    toasts: Readonly<import('vue').Ref<readonly {
+        readonly id: number;
+        readonly message: string;
+        readonly tone: ToastTone;
+        readonly duration: number;
+    }[], readonly {
+        readonly id: number;
+        readonly message: string;
+        readonly tone: ToastTone;
+        readonly duration: number;
+    }[]>>;
+    info: (message: string, options?: ToastOptions) => number;
+    success: (message: string, options?: ToastOptions) => number;
+    warning: (message: string, options?: ToastOptions) => number;
+    danger: (message: string, options?: ToastOptions) => number;
+    dismiss: typeof dismiss;
+    dismissAll: typeof dismissAll;
+    pause: typeof pause;
+    resume: typeof resume;
+};
+export {};

package/dist/index.d.ts

@@ -40,6 +40,8 @@ export { useDebouncedCallback } from './composables/use-debounced-callback';
 export { useDragScroll } from './composables/use-drag-scroll';
 export { useMediaQuery } from './composables/use-media-query';
 export { useVisualViewport } from './composables/use-visual-viewport';
+export { useToast } from './composables/use-toast';
+export type { Toast, ToastOptions, ToastTone } from './composables/use-toast';
 export type { VisualViewportRect } from './composables/use-visual-viewport';
 export { default as BaseAlert } from './components/BaseAlert.vue';
 export { default as BaseBadge } from './components/BaseBadge.vue';
@@ -64,6 +66,7 @@ export { default as SettingsGroup } from './components/SettingsGroup.vue';
 export { default as SettingsRow } from './components/SettingsRow.vue';
 export { default as SkeletonList } from './components/SkeletonList.vue';
 export { default as StatCard } from './components/StatCard.vue';
+export { default as ToastHost } from './components/ToastHost.vue';
 export { default as ToneDot } from './components/ToneDot.vue';
 export type { Tone } from './components/SectionHeading.vue';
 export { default as LocaleLinks } from './components/LocaleLinks.vue';