rei-kit 0.7.1 → 0.9.0

package/README.md

@@ -108,12 +108,13 @@ import { createSupabaseClient } from 'rei-kit/supabase'
 
 ### Wiring the styles
 
-Four lines, and all four are load-bearing:
+Four lines, and every one is load-bearing:
 
 ```css
 /* your app's main.css */
 @import 'tailwindcss';
 @import 'rei-kit/tokens.css'; /* colour roles, the dark variant, measures, utilities */
+@import 'rei-kit/shell/mobile.css'; /* or shell/web.css — see The shell, below */
 @import 'rei-kit/styles.css'; /* compiled component styles */
 
 /* Tailwind generates a utility only where it has seen the class, and it does
@@ -125,10 +126,10 @@ Four lines, and all four are load-bearing:
 The path is relative to the CSS file, so adjust the `../` depth to where your
 `main.css` sits.
 
-**Leaving any of the four out fails quietly:** the build succeeds, the
+**Leaving any of these out fails quietly:** the build succeeds, the
 components mount, and they come out unstyled. Nothing type-checks this, so it
 is worth a test — Hibi's `kit-styling.spec.ts` reads its own stylesheet and
-asserts all four, at unit-test speed. Copy it.
+asserts them, at unit-test speed. Copy it.
 
 That test exists because the failure is real: Hibi shipped with the tab bar
 invisible once, and separately spent three versions restating `tokens.css`
@@ -183,12 +184,22 @@ it — the same mistake as a hex inside a component, one axis over.
 }
 ```
 
-### The phone shell
+### The shell
 
-`tokens.css` also carries the geometry of a phone shell — `shell-frame`,
-`page-slide`, `page-auth` and the slide transitions between screens. All of it
-is opt-in: nothing applies unless you put the class on an element, so a wide
-app can ignore it. Two of the three consumers use it.
+Tokens are what every app needs. A shell is a decision about what shape the app
+is, so it is a separate import and there are two of them.
+
+|                            |                                                                                                                                                                      |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rei-kit/shell/mobile.css` | `shell-frame` (a 430px column at viewport height), `page-slide` and `page-auth` scroll containers, and the sliding transition between screens                        |
+| `rei-kit/shell/web.css`    | `.shell` — the page's column as a class, for a header or footer whose bar spans the window while its contents line up with the text — and a short fade between pages |
+
+Both are opt-in throughout: nothing applies until a class lands on an element,
+and both read `--measure-page` rather than declaring a width of their own.
+
+They were one file until 0.9.0, and it was `tokens.css` — so a wide course site
+downloaded a 430px column, a full-viewport height and an iOS sheet curve in
+order to ignore them, and had no counterpart of its own.
 
 ### Prerendering
 

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';