rei-kit 0.4.4 → 0.5.1

package/README.md

@@ -1,22 +1,47 @@
 # rei-kit
 
-Vue 3 and Tailwind 4 design system and shared runtime. Extracted from
-[Hibi](https://github.com/ramazandogna/hibi).
+Vue 3 and Tailwind 4 design system and shared runtime.
 
 零 — the layer everything else starts from.
 
 ## Why it exists
 
-Hibi's shared layer turned out to be genuinely portable: no file under
-`shared/` imported from `features/`, so the components, the date and theme
-helpers, and the i18n runtime could leave without being rewritten. This is that
-layer, packaged so the next app installs it instead of copying it.
+**The kit distributes decisions, not a look.** Three apps run on it and no two
+resemble each other: a phone journal, a phone ledger, and a wide Japanese
+course site. None of them forked it, because there is not a single hex value
+inside a component. Colours are named for the role they play, and an app
+rebrands by redefining eleven values.
+
+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.
 
 ## Status
 
-**v0.0.0 — extraction complete, no consumer yet.** Thirteen components,
-eight utilities, six composables, a generic i18n runtime and an optional
-Supabase entry. Hibi moves onto it next.
+**v0.4.4 — three consumers.**
+
+|             |                                                                                                                                                        |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Components  | 22                                                                                                                                                     |
+| Composables | 11                                                                                                                                                     |
+| Utilities   | 20                                                                                                                                                     |
+| Also        | a generic i18n runtime, an optional Supabase entry                                                                                                     |
+| Consumers   | [Hibi](https://github.com/ramazandogna/hibi) · [Kakei](https://github.com/ramazandogna/kakei) · [Kakehashi](https://github.com/ramazandogna/kakehashi) |
+
+Every export is listed by name in `src/__tests__/public-api.spec.ts`, which is
+the package's promise written down.
 
 ## Install
 
@@ -37,7 +62,7 @@ is the only copy:
 | `@supabase/supabase-js` | the `rei-kit/supabase` entry only |
 
 This is not a formality. A second copy of a library that works through
-provide/inject is not a spare copy -- it is a different injection key, so the
+provide/inject is not a spare copy — it is a different injection key, so the
 app's own provider becomes invisible and the component throws on mount.
 
 ## Use
@@ -59,12 +84,12 @@ import { createSupabaseClient } from 'rei-kit/supabase'
 
 ### Wiring the styles
 
-Three lines, and all three are load-bearing:
+Four lines, and all four are load-bearing:
 
 ```css
 /* your app's main.css */
 @import 'tailwindcss';
-@import 'rei-kit/tokens.css'; /* colour roles, the dark variant, utilities */
+@import 'rei-kit/tokens.css'; /* colour roles, the dark variant, measures, utilities */
 @import 'rei-kit/styles.css'; /* compiled component styles */
 
 /* Tailwind generates a utility only where it has seen the class, and it does
@@ -76,27 +101,19 @@ Three lines, and all three 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 three out fails quietly: the build succeeds, the components
-mount, and they come out unstyled. Nothing type-checks this, so it is worth a
-test -- see _Not breaking the apps that use it_.
-
-### Prerendering
+**Leaving any of the four 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.
 
-The kit imports and renders on a server, so an app can prerender with
-`vite-ssg` or any other SSR build. Two things stay the app's job, because only
-the app knows the answer:
-
-- **The theme.** `applyTheme` does nothing without a document, so prerendered
-  HTML carries no `.dark`. Set it before hydration with a small synchronous
-  script in `index.html`, or the first paint flashes light.
-- **Today's date.** `useToday()` on a server is the *server's* today, a
-  different day from the visitor's either side of midnight. Render anything
-  derived from it on the client.
+That test exists because the failure is real: Hibi shipped with the tab bar
+invisible once, and separately spent three versions restating `tokens.css`
+locally instead of importing it, which nothing noticed.
 
 ### Colours
 
-`tokens.css` defines all eleven roles, a `.dark` block for each surface, and the
-`dark` variant. A new app rebrands by overriding values, never by renaming:
+`tokens.css` defines all eleven roles, a `.dark` block for each surface, and
+the `dark` variant. A new app rebrands by overriding values, never by renaming:
 
 ```css
 @theme {
@@ -125,8 +142,52 @@ the app's own dark-mode overrides carry into the kit's components:
 }
 ```
 
-Tokens are named for what they do, not for the app they came from, so a new
-product changes values rather than renaming anything.
+Put your own `.dark` block _after_ the import. Both blocks match at the same
+specificity, so the later one wins — which is what makes the override work.
+
+### Measures
+
+Widths are roles too. `PageContainer` shipped with `75rem` baked in, and the
+first app that wanted it had deliberately measured its page at 1120px, so the
+component written to remove that app's hand-rolled container could not replace
+it — the same mistake as a hex inside a component, one axis over.
+
+```css
+@theme {
+  --measure-page: 1120px; /* a page */
+  --measure-reading: 68ch; /* a column of prose */
+}
+```
+
+### The phone 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.
+
+### Prerendering
+
+The kit imports and renders on a server, so an app can prerender with
+`vite-ssg` or any other SSR build. Two things stay the app's job, because only
+the app knows the answer:
+
+- **The theme.** `applyTheme` does nothing without a document, so prerendered
+  HTML carries no `.dark`. Set it before hydration with a small synchronous
+  script in `index.html`, or the first paint flashes light.
+- **Today's date.** `useToday()` on a server is the _server's_ today, a
+  different day from the visitor's either side of midnight. Render anything
+  derived from it on the client.
+
+## Seeing what is in it
+
+```sh
+pnpm showcase
+```
+
+A page that wires the kit exactly the way this README says to, so a broken
+install shows up there before it ships. A component nobody can see is a
+component nobody uses.
 
 ## Commands
 
@@ -135,26 +196,34 @@ product changes values rather than renaming anything.
 | `pnpm dev`       | Rebuild on change, for use with a linked app          |
 | `pnpm build`     | Type-check, then build                                |
 | `pnpm check`     | Everything CI runs: format, lint, types, tests, build |
+| `pnpm showcase`  | The showcase, in dev mode                             |
 | `pnpm test:unit` | Vitest, watch mode                                    |
 | `pnpm lint`      | oxlint + ESLint, with `--fix`                         |
 
 ## Not breaking the apps that use it
 
-Three layers, cheapest first.
+Four layers, cheapest first.
 
-**Pinned ranges.** A consumer depends on `^0.1.0`, which at 0.x means
-`>=0.1.0 <0.2.0` — publishing 0.2.0 upgrades nobody. Apps move on their own
-schedule, and a release can never reach an app that has not asked for it.
+**Pinned ranges.** A consumer depends on `^0.4.0`, which at 0.x means
+`>=0.4.0 <0.5.0` — publishing 0.5.0 upgrades nobody. Apps move on their own
+schedule, and a release can never reach an app that has not asked for it. The
+cost is the mirror image: an app that never asks never moves. Two of these
+three sat two minors behind, so `PATCHNOTES.md` exists to make taking one a
+short read.
 
 **The public API test.** `src/__tests__/public-api.spec.ts` lists every export
 by name. The kit compiles perfectly well without an export nothing here calls,
 so removing one is invisible to every other test; this one fails loudly and
 asks whether the version should be a major.
 
+**The SSR test.** `src/__tests__/ssr.spec.ts` renders in the **node**
+environment, not jsdom — jsdom supplies the very `document` a server lacks, and
+passed all four of the SSR bugs 0.2.2 fixed.
+
 **The consumer check.** `.github/workflows/consumer.yml` packs the tarball npm
-would serve, installs it into Hibi, and runs Hibi's full gate — format, lint,
-types, 37 tests, production build. A renamed prop shows up as a red pull
-request here rather than as a broken app after release.
+would serve and installs it into **all three** apps, running each one's full
+gate — format, lint, types, tests, production build. Kakehashi's build is
+`vite-ssg build`, so that job is also the real prerender.
 
 That last one is the important one: the kit's own tests never import it the way
 an app does.
@@ -169,6 +238,9 @@ pnpm version minor
 git push --follow-tags
 ```
 
+Then write the release into `PATCHNOTES.md` — what a consumer gains, and what
+they have to do to take it.
+
 ## License
 
 MIT

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

@@ -1,13 +1,45 @@
+/**
+ * The kit's button, and — when asked — its link.
+ *
+ * `as` exists because a button and a link are the same shape and a different
+ * element, and the app was resolving that by nesting them: a consumer had
+ * `<RouterLink><BaseButton>` in every call to action, which is an `<a>` around
+ * a `<button>`. That is invalid HTML, two stops in the tab order and two
+ * controls to a screen reader, for one thing on the screen. Whether something
+ * navigates is the app's decision; carrying it is this component's job.
+ *
+ * `router-link` is resolved by name rather than imported, so `vue-router` stays
+ * the optional peer it is. Only an app that passes `as="router-link"` needs it,
+ * and an app that passes it has it.
+ */
 type __VLS_Props = {
+    /** What to render. `button` unless this navigates. */
+    as?: 'button' | 'a' | 'router-link' | undefined;
     variant?: 'primary' | 'secondary' | 'ghost' | 'danger' | undefined;
-    size?: 'sm' | 'md' | undefined;
+    size?: 'sm' | 'md' | 'lg' | undefined;
     loading?: boolean | undefined;
     disabled?: boolean | undefined;
+    /** Ignored unless `as` is `button`. */
     type?: 'button' | 'submit' | undefined;
+    /**
+     * Square, sized to its icon, with no label beside it.
+     *
+     * **Pass `aria-label`.** An icon on its own has no accessible name, and a
+     * control a screen reader announces as "button" is not usable. Attributes
+     * fall through, so `aria-label` lands where it should — nothing here can
+     * check that you passed one, which is why it is said this loudly.
+     */
+    icon?: boolean | undefined;
+    /** Fills its container. The ordinary case under a form. */
+    block?: boolean | undefined;
+    /** For `as="router-link"`. */
+    to?: string | Record<string, unknown> | undefined;
+    /** For `as="a"`. */
+    href?: string | undefined;
 };
-declare var __VLS_1: {};
+declare var __VLS_8: {};
 type __VLS_Slots = {} & {
-    default?: (props: typeof __VLS_1) => any;
+    default?: (props: typeof __VLS_8) => any;
 };
 declare const __VLS_base: 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 __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;

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

@@ -0,0 +1,39 @@
+/**
+ * A single checkbox, with its label beside it.
+ *
+ * Deliberately not built on `FormField`. That component stacks a label above
+ * its control, which is right for every field where the control is a box you
+ * type into and wrong here: a checkbox is read as one sentence with a mark in
+ * front of it, and putting the words above the box breaks the association a
+ * sighted reader makes before they get to the accessible name.
+ *
+ * The whole row is the label, so the words are part of the hit target. On a
+ * phone that is the difference between a control and a coin toss.
+ */
+type __VLS_Props = {
+    label: string;
+    error?: string | undefined;
+    hint?: string | undefined;
+    disabled?: boolean | undefined;
+    /**
+     * `md` is a setting: a line the reader came here to change, in ink.
+     * `sm` is an aside — "remember me" under a sign-in form, "show the ones I
+     * have learned" above a list — quieter and tighter.
+     *
+     * The two are not a guess. Of the five hand-written checkboxes across the
+     * three consuming apps, four were the aside and one was the setting, and
+     * they differed in exactly these two ways.
+     */
+    size?: 'sm' | 'md' | undefined;
+};
+type __VLS_ModelProps = {
+    modelValue?: boolean;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_export: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:modelValue": (value: boolean) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: (value: boolean) => any;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

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

@@ -9,6 +9,8 @@ type __VLS_Props = {
      */
     labelHidden?: boolean | undefined;
     type?: 'text' | 'email' | 'password' | 'number' | undefined;
+    /** `sm` for a field inside a row rather than in a form of its own. */
+    size?: 'sm' | 'md' | undefined;
 };
 type __VLS_ModelProps = {
     modelValue?: string | undefined;

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

@@ -0,0 +1,33 @@
+/**
+ * A set of radios, and the reason there is no `BaseRadio`.
+ *
+ * One radio on its own is not a control — it is half of a choice that cannot
+ * be unmade, and every real use is a group. So the group is the component.
+ *
+ * `fieldset` and `legend` rather than a label: a label points at one element,
+ * and the thing being named here is the question, not any single answer. Left
+ * as a plain label, a screen reader reads the options with no idea what they
+ * are options for.
+ */
+type __VLS_Props = {
+    legend: string;
+    options: readonly {
+        value: string;
+        label: string;
+        disabled?: boolean | undefined;
+    }[];
+    error?: string | undefined;
+    hint?: string | undefined;
+    legendHidden?: boolean | undefined;
+};
+type __VLS_ModelProps = {
+    modelValue?: string | undefined;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_export: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:modelValue": (value: string | undefined) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: (value: string | undefined) => any;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

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

@@ -0,0 +1,46 @@
+/**
+ * A native `<select>`, wearing the kit's field.
+ *
+ * Native on purpose. A custom listbox has to reimplement typeahead, the
+ * keyboard, and the way a phone lifts the options into its own picker — and it
+ * gets one of them wrong. What is worth replacing is the chrome, so the arrow
+ * is drawn and the browser's own is removed.
+ *
+ * Options are passed rather than slotted so the value can be anything and the
+ * label can be a translated string the kit never sees.
+ */
+type __VLS_Props = {
+    label: string;
+    options: readonly {
+        value: string;
+        label: string;
+        disabled?: boolean | undefined;
+    }[];
+    error?: string | undefined;
+    hint?: string | undefined;
+    labelHidden?: boolean | undefined;
+    /**
+     * An unselectable first row, for a field with no sensible default.
+     *
+     * Disabled rather than merely empty: an empty option that can be chosen lets
+     * someone go back to having answered nothing, which no form wants.
+     */
+    placeholder?: string | undefined;
+    /**
+     * `sm` for a select that filters or sorts rather than answers a form.
+     *
+     * Every hand-written select across the three consuming apps was this one.
+     */
+    size?: 'sm' | 'md' | undefined;
+};
+type __VLS_ModelProps = {
+    modelValue?: string | undefined;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_export: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:modelValue": (value: string | undefined) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: (value: string | undefined) => any;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

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

@@ -0,0 +1,20 @@
+type __VLS_Props = {
+    label: string;
+    error?: string | undefined;
+    hint?: string | undefined;
+    labelHidden?: boolean | undefined;
+    rows?: number | undefined;
+    /** `sm` for editing in place, inside a row that is already small. */
+    size?: 'sm' | 'md' | undefined;
+};
+type __VLS_ModelProps = {
+    modelValue?: string | undefined;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_export: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:modelValue": (value: string | undefined) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: (value: string | undefined) => any;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

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

@@ -0,0 +1,61 @@
+/**
+ * A label, a hint, an error, and the wiring between them.
+ *
+ * This was inside `BaseInput`, which is why the kit had one form control
+ * instead of five. The hard part of a field is not the `<input>` — it is
+ * generating an id, pointing the label at it, deciding whether the description
+ * is the hint or the error, and telling assistive tech which one to read. That
+ * is identical for a select, a textarea and an input, and every app that
+ * needed one of the other two wrote the whole thing again.
+ *
+ * The control comes in through the slot and is handed what it needs to be
+ * described. It is a slot rather than a prop so the field never has to know
+ * what it is wrapping.
+ *
+ * @example
+ * ```vue
+ * <FormField :label="t('profile.name')" :error="errors.name">
+ *   <template #default="{ id, describedBy, invalid }">
+ *     <input :id="id" :aria-describedby="describedBy" :aria-invalid="invalid" />
+ *   </template>
+ * </FormField>
+ * ```
+ */
+type __VLS_Props = {
+    label: string;
+    error?: string | undefined;
+    hint?: string | undefined;
+    /**
+     * `sm` for a control that sits inside something else — a toolbar, a filter
+     * row, a settings line — rather than in a form of its own.
+     *
+     * It exists because every hand-written select in all three apps was the
+     * small one, and the kit only had the large one. A part is not reusable if
+     * reaching for it costs a size somebody chose on purpose.
+     */
+    size?: 'sm' | 'md' | undefined;
+    /**
+     * Hides the label visually but keeps it for assistive tech. For fields whose
+     * surrounding row already names them — dropping the label entirely would
+     * leave the control with no accessible name at all.
+     */
+    labelHidden?: boolean | undefined;
+};
+declare var __VLS_1: {
+    id: string;
+    describedBy: string | undefined;
+    invalid: boolean;
+    size: "sm" | "md";
+};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: 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 __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/index.d.ts

@@ -47,7 +47,12 @@ export { default as BaseButton } from './components/BaseButton.vue';
 export { default as BaseInput } from './components/BaseInput.vue';
 export { default as BaseSheet } from './components/BaseSheet.vue';
 export { default as BaseCard } from './components/BaseCard.vue';
+export { default as BaseCheckbox } from './components/BaseCheckbox.vue';
+export { default as BaseRadioGroup } from './components/BaseRadioGroup.vue';
+export { default as BaseSelect } from './components/BaseSelect.vue';
+export { default as BaseTextarea } from './components/BaseTextarea.vue';
 export { default as EmptyState } from './components/EmptyState.vue';
+export { default as FormField } from './components/FormField.vue';
 export { default as ErrorBoundary } from './components/ErrorBoundary.vue';
 export { default as PageContainer } from './components/PageContainer.vue';
 export { default as PageHeader } from './components/PageHeader.vue';