@jovertical/mise-design-system 0.0.0-stage → 1.1.0

package/skills/mise/recipes/form-sveltekit.svelte

@@ -0,0 +1,79 @@
+<!--
+  The same "new stock item" form in a SvelteKit app, through `mise/form`:
+  superforms validates on the client and in the form action, and the Form
+  parts link each label, description and error to its control. This is a
+  page component (+page.svelte); its load and action are in form.md.
+
+  SvelteKit only: superforms imports `$app/*`. In an Inertia or plain Vite app
+  use form.svelte instead.
+-->
+<script lang="ts" module>
+  import { z } from 'zod'
+
+  /** Shared with +page.server.ts, which validates the same schema on submit. */
+  export const stockItemSchema = z.object({
+    name: z.string().min(2, 'Name the item.'),
+    category: z.enum(['dry', 'dairy', 'produce'], { message: 'Choose a category.' }),
+    /** Integer cents. */
+    unitCost: z.number().int().min(0).nullable(),
+    tracksExpiry: z.boolean().default(false),
+  })
+</script>
+
+<script lang="ts">
+  import { Input, NumberInput, SwitchField } from '@jovertical/mise-design-system'
+  import {
+    Form,
+    FormButton,
+    FormControl,
+    FormDescription,
+    FormField,
+    FormFieldErrors,
+    FormLabel,
+  } from '@jovertical/mise-design-system/form'
+  import { untrack } from 'svelte'
+  import { type Infer, type SuperValidated, superForm } from 'sveltekit-superforms'
+  import { zod4 } from 'sveltekit-superforms/adapters'
+
+  let { data }: { data: { form: SuperValidated<Infer<typeof stockItemSchema>> } } = $props()
+
+  // Created once for the page; superforms keeps it in step with later loads.
+  // `json` posts the bound values as they are, so the switch needs no input
+  // name and the cents stay a number.
+  const form = superForm(
+    untrack(() => data.form),
+    { validators: zod4(stockItemSchema), dataType: 'json' },
+  )
+  const { form: values } = form
+</script>
+
+<Form {form} method="POST" class="flex max-w-xl flex-col gap-6">
+  <FormField {form} name="name">
+    <FormControl>
+      {#snippet children({ props })}
+        <FormLabel required>Name</FormLabel>
+        <Input {...props} bind:value={$values.name} placeholder="All-purpose flour, 25 kg" />
+      {/snippet}
+    </FormControl>
+    <FormFieldErrors />
+  </FormField>
+
+  <FormField {form} name="unitCost">
+    <FormControl>
+      {#snippet children({ props })}
+        <FormLabel>Unit cost</FormLabel>
+        <NumberInput {...props} format="currency" prefix="$" bind:value={$values.unitCost} />
+      {/snippet}
+    </FormControl>
+    <FormDescription>In dollars and cents; stored as cents.</FormDescription>
+    <FormFieldErrors />
+  </FormField>
+
+  <SwitchField
+    id="tracks-expiry"
+    label="Track expiry dates"
+    bind:checked={$values.tracksExpiry}
+  />
+
+  <FormButton class="self-start">Save item</FormButton>
+</Form>

package/skills/mise/recipes/form.md

@@ -0,0 +1,82 @@
+# Recipe: a form
+
+A "new stock item" form, in two versions: [form.svelte](form.svelte) for Inertia or plain Svelte,
+and [form-sveltekit.svelte](form-sveltekit.svelte) for SvelteKit through `mise/form`. Both
+type-check against the current mise.
+
+## What it is made of
+
+- `Card` ([layout](../components/layout.md)) as the surface, `FieldGroup` for the spacing.
+- `Field`, `FieldLabel`, `FieldDescription` and `FieldError` ([forms](../components/forms.md))
+  around each control: `Input`, `Select`, `QuantityInput`, `NumberInput`.
+- `SwitchField` for an on/off setting with a label and a description in one row.
+- `Button` with a `Spinner` while the form submits.
+
+## Inertia (form.svelte)
+
+mise does not validate; the app does, and mise shows the result. The component takes the item,
+the errors and the processing flag as props, so with Inertia it is driven by `useForm`:
+
+```svelte
+<script lang="ts">
+  import { useForm } from '@inertiajs/svelte'
+  import StockItemForm from './StockItemForm.svelte'
+
+  const form = useForm({
+    name: '',
+    category: '',
+    unit: 'kg',
+    openingStock: null,
+    unitCost: null,
+    tracksExpiry: false,
+  })
+</script>
+
+<StockItemForm
+  bind:item={$form}
+  errors={$form.errors}
+  processing={$form.processing}
+  onsubmit={() => $form.post('/stock-items')}
+/>
+```
+
+Laravel's validation errors arrive keyed by field name; each `Field` sets `data-invalid` and its
+control `aria-invalid` when its key is present, and `FieldError` shows the message.
+
+## SvelteKit (form-sveltekit.svelte)
+
+`Form`, `FormField`, `FormControl`, `FormLabel`, `FormDescription`, `FormFieldErrors` and
+`FormButton` come from `@jovertical/mise-design-system/form`. superforms validates in the browser
+with the same schema the server action uses. The page's server file:
+
+```ts
+// +page.server.ts
+import { fail } from '@sveltejs/kit'
+import { superValidate } from 'sveltekit-superforms'
+import { zod4 } from 'sveltekit-superforms/adapters'
+import { stockItemSchema } from './+page.svelte'
+
+export const load = async () => ({ form: await superValidate(zod4(stockItemSchema)) })
+
+export const actions = {
+  default: async ({ request }) => {
+    const form = await superValidate(request, zod4(stockItemSchema))
+    if (!form.valid) return fail(400, { form })
+    // save form.data
+    return { form }
+  },
+}
+```
+
+In a real app, move `stockItemSchema` to its own module (`$lib/schemas/stock-item.ts`) and import
+it from both files.
+
+## Decisions worth copying
+
+- **Money is integer cents.** `NumberInput format="currency"` shows `$12.50` and binds `1250`, so
+  no price is ever a float.
+- **An amount and its unit are one control.** `QuantityInput` makes "2.5" without "kg"
+  impossible to submit.
+- **`Select` gets `items`**, so its trigger shows the chosen label while the list is closed.
+- **A required field says so** with `FieldLabel required`: an asterisk for the eye and
+  "(required)" for a screen reader.

package/skills/mise/recipes/form.svelte

@@ -0,0 +1,158 @@
+<!--
+  A "new stock item" form for an Inertia or plain Svelte app. The form state
+  is the app's: with Inertia it is `useForm`, and `errors` and `processing`
+  come from it (see form.md). mise draws the fields, the labels, the errors
+  and the invalid state; it does not validate.
+-->
+<script lang="ts">
+  import {
+    Button,
+    Card,
+    CardContent,
+    CardFooter,
+    CardHeader,
+    CardTitle,
+    Field,
+    FieldDescription,
+    FieldError,
+    FieldGroup,
+    FieldLabel,
+    Input,
+    NumberInput,
+    QuantityInput,
+    type QuantityUnit,
+    Select,
+    SelectContent,
+    SelectItem,
+    SelectTrigger,
+    SelectValue,
+    Spinner,
+    SwitchField,
+  } from '@jovertical/mise-design-system'
+
+  type StockItem = {
+    name: string
+    category: string
+    unit: string
+    openingStock: number | null
+    /** Integer cents: NumberInput's currency format speaks minor units. */
+    unitCost: number | null
+    tracksExpiry: boolean
+  }
+
+  let {
+    item = $bindable({
+      name: '',
+      category: '',
+      unit: 'kg',
+      openingStock: null,
+      unitCost: null,
+      tracksExpiry: false,
+    }),
+    errors = {},
+    processing = false,
+    onsubmit,
+  }: {
+    item?: StockItem
+    /** Field name to message, as Laravel's validation returns them. */
+    errors?: Partial<Record<keyof StockItem, string>>
+    processing?: boolean
+    onsubmit: () => void
+  } = $props()
+
+  const categories = [
+    { value: 'dry', label: 'Dry goods' },
+    { value: 'dairy', label: 'Dairy' },
+    { value: 'produce', label: 'Produce' },
+  ]
+
+  const units: QuantityUnit[] = [
+    { value: 'kg', label: 'Kilogram (kg)', short: 'kg', group: 'Mass' },
+    { value: 'g', label: 'Gram (g)', short: 'g', group: 'Mass' },
+    { value: 'l', label: 'Litre (l)', short: 'l', group: 'Volume' },
+    { value: 'pc', label: 'Piece', short: 'pc', group: 'Count' },
+  ]
+
+  const errorFor = (field: keyof StockItem) => (errors[field] ? [{ message: errors[field] }] : [])
+
+  function submit(event: SubmitEvent) {
+    event.preventDefault()
+    onsubmit()
+  }
+</script>
+
+<form onsubmit={submit}>
+  <Card class="max-w-xl">
+    <CardHeader>
+      <CardTitle>New stock item</CardTitle>
+    </CardHeader>
+
+    <CardContent>
+      <FieldGroup>
+        <Field data-invalid={errors.name ? 'true' : undefined}>
+          <FieldLabel for="item-name" required>Name</FieldLabel>
+          <Input
+            id="item-name"
+            bind:value={item.name}
+            placeholder="All-purpose flour, 25 kg"
+            aria-invalid={errors.name ? 'true' : undefined}
+          />
+          <FieldError errors={errorFor('name')} />
+        </Field>
+
+        <Field data-invalid={errors.category ? 'true' : undefined}>
+          <FieldLabel for="item-category" required>Category</FieldLabel>
+          <Select type="single" bind:value={item.category} items={categories}>
+            <SelectTrigger id="item-category" aria-invalid={errors.category ? 'true' : undefined}>
+              <SelectValue placeholder="Choose a category" />
+            </SelectTrigger>
+            <SelectContent>
+              {#each categories as category (category.value)}
+                <SelectItem value={category.value} label={category.label} />
+              {/each}
+            </SelectContent>
+          </Select>
+          <FieldError errors={errorFor('category')} />
+        </Field>
+
+        <Field data-invalid={errors.openingStock ? 'true' : undefined}>
+          <FieldLabel>Opening stock</FieldLabel>
+          <QuantityInput
+            {units}
+            bind:unit={item.unit}
+            bind:quantity={item.openingStock}
+            quantityPlaceholder="0"
+          />
+          <FieldDescription>What is on the shelf today, counted.</FieldDescription>
+          <FieldError errors={errorFor('openingStock')} />
+        </Field>
+
+        <Field data-invalid={errors.unitCost ? 'true' : undefined}>
+          <FieldLabel for="item-cost">Unit cost</FieldLabel>
+          <NumberInput
+            id="item-cost"
+            format="currency"
+            prefix="$"
+            bind:value={item.unitCost}
+            aria-invalid={errors.unitCost ? 'true' : undefined}
+          />
+          <FieldError errors={errorFor('unitCost')} />
+        </Field>
+
+        <SwitchField
+          id="item-expiry"
+          label="Track expiry dates"
+          description="Ask for a use-by date when this item is received."
+          bind:checked={item.tracksExpiry}
+        />
+      </FieldGroup>
+    </CardContent>
+
+    <CardFooter class="justify-end">
+      <Button type="submit" disabled={processing}>
+        {#if processing}<Spinner />{/if}
+        Save item
+      </Button>
+    </CardFooter>
+  </Card>
+</form>

package/skills/mise/setup.md

@@ -0,0 +1,99 @@
+# Setting mise up
+
+mise is a Svelte 5 library styled by Tailwind CSS v4. Setting it up is an install and four lines
+of CSS. No app-wide provider is required: components are imported where they are used, a
+`Tooltip` brings its own provider, and the `Sidebar` family has its own `SidebarProvider` as
+part of the shell. `ThemeProvider` is optional (see Dark mode).
+
+## Install
+
+```sh
+pnpm add @jovertical/mise-design-system
+pnpm add -D tailwindcss tw-animate-css
+```
+
+With npm: `npm install @jovertical/mise-design-system` and
+`npm install -D tailwindcss tw-animate-css`. `svelte`, `tailwindcss` and `tw-animate-css` are
+peer dependencies; the app's own stylesheet imports all three, so they resolve from its install.
+
+Tailwind v4 runs through its Vite plugin, `@tailwindcss/vite`, in the app's Vite config.
+
+## The stylesheet
+
+In the app's main stylesheet:
+
+```css
+@import 'tailwindcss';
+@import 'tw-animate-css';
+@import '@jovertical/mise-design-system/theme.css';
+@source '<relative path>/node_modules/@jovertical/mise-design-system/dist';
+```
+
+The `@source` line is required. Tailwind v4 skips `node_modules` when it looks for class names,
+so without it every mise component renders unstyled. The path is relative to the stylesheet;
+the sections below give it for each stack.
+
+To use a generated theme ([theming.md](theming.md)), import that file instead of `theme.css`.
+
+## SvelteKit
+
+- The stylesheet is `src/app.css`, imported once from `src/routes/+layout.svelte`:
+  `import '../app.css'`.
+- The `@source` path is `'../node_modules/@jovertical/mise-design-system/dist'`.
+- `Form` is available from `@jovertical/mise-design-system/form` once its optional peers are
+  installed: `pnpm add formsnap sveltekit-superforms` (and a validator such as `zod`).
+
+## Laravel with Inertia and Svelte
+
+- The stylesheet is `resources/css/app.css`, which `laravel({ input: [...] })` in
+  `vite.config.js` (or `.ts`) already lists as an entry, with `@tailwindcss/vite` among the
+  plugins.
+- The `@source` path is `'../../node_modules/@jovertical/mise-design-system/dist'`.
+- Import components in the pages under `resources/js/Pages/` like any Svelte module.
+- **`mise/form` is not available.** Its `sveltekit-superforms` dependency imports SvelteKit's
+  `$app/*` modules, which a plain Vite build cannot resolve. Build forms with `Field` and the
+  inputs, and keep the state in Inertia's `useForm`; Laravel's validation errors arrive in
+  `form.errors` ([recipes/form.md](recipes/form.md)).
+
+## Plain Svelte with Vite
+
+- Import the stylesheet from the entry module (`src/main.ts`): `import './app.css'`.
+- The `@source` path is relative to wherever that stylesheet lives, usually
+  `'../node_modules/@jovertical/mise-design-system/dist'`.
+- As with Inertia, use `Field` rather than `mise/form`.
+
+## Dark mode
+
+Dark mode is the `.dark` class on an ancestor, usually `<html>`. Either the app sets it itself,
+or `ThemeProvider` does: it applies `light` or `dark` to `<html>`, follows the system setting by
+default (`defaultTheme="system"`), and stores the choice under `storageKey`. Give each app its
+own `storageKey`, so two apps on one host do not share a theme. `ThemeToggle` is the switch, and
+`useTheme()` reads or sets the theme from code; both need the provider above them.
+
+```svelte
+<script lang="ts">
+  import { ThemeProvider } from '@jovertical/mise-design-system'
+
+  let { children } = $props()
+</script>
+
+<ThemeProvider storageKey="ops-theme">
+  {@render children()}
+</ThemeProvider>
+```
+
+## Toasts
+
+Render `Toaster` once in the app's root layout, then call `toast('Order saved')` (also
+`toast.success`, `toast.error` and the rest of `svelte-sonner`'s API) from anywhere.
+
+## Check it
+
+```sh
+npx --no-install mise-theme info --json
+```
+
+It prints the installed version, the stack it detected, and `stylesheet`, the CSS file it found
+importing mise. `"stylesheet": null` means the import above is missing or sits in a file it did
+not search (`node_modules`, `vendor`, `public`, `storage`, `dist`, `build` and dot-folders are
+skipped).

package/skills/mise/theming.md

@@ -0,0 +1,82 @@
+# Theming mise
+
+A component never carries a colour of its own: it reads the semantic tokens (`--primary`,
+`--muted-foreground`, `--success`) and the tone maps built on them. So the way to change how mise
+looks is to change the tokens, never to override a component's classes. Recolouring `--success`
+recolours every success badge, alert, bar and toast together.
+
+There are three levels, each optional. Use the lowest one that does the job.
+
+## 1. The default
+
+The imports in [setup.md](setup.md) are all it takes: a zinc base, an indigo brand, system
+fonts, and a light and a dark scheme.
+
+## 2. Override tokens in CSS
+
+For a brand colour, a radius or a font, override the tokens after the import:
+
+```css
+@import '@jovertical/mise-design-system/theme.css';
+
+:root {
+  --primary: oklch(0.6 0.15 160);
+  --radius: 0.5rem;
+  --font-sans: 'Inter', system-ui, sans-serif;
+}
+
+.dark {
+  --primary: oklch(0.75 0.13 160);
+}
+```
+
+The tokens are a documented contract, listed in `SEMANTIC_TOKENS` (exported from
+`@jovertical/mise-design-system/tokens`): `--background`, `--foreground`, `--card`,
+`--popover`, `--primary`, `--secondary`, `--muted`, `--accent`, `--destructive`, `--info`,
+`--success`, `--warning`, each `-foreground` pair, `--border`, `--input`, `--ring`,
+`--chart-1` to `--chart-5`, the `--sidebar-*` set and `--color-table-header`. Also `--radius`,
+`--font-sans`, `--font-heading` and `--font-mono`.
+
+The `-soft` tints (`bg-success-soft` and the like) are mixed from their ink, so they follow an
+override on their own. `--accent` is the active navigation row only; it is not a second brand
+colour.
+
+## 3. A theme from a config
+
+For a different base grey, a whole brand ramp, or a different hue for a status, write a config
+and generate a stylesheet from it:
+
+```js
+// mise.theme.js
+import { defineTheme } from '@jovertical/mise-design-system/tokens'
+
+export default defineTheme({
+  base: 'stone', // zinc | slate | gray | neutral | stone
+  primary: 'teal', // a Tailwind hue name, or a custom ramp with all of 50 to 950
+  status: { warning: 'orange' }, // info | success | warning | critical
+  charts: ['teal', 'sky', 'amber', 'rose', 'violet'],
+  radius: '0.5rem',
+  fonts: { sans: "'Inter', system-ui, sans-serif" }, // sans | heading | mono
+  light: { '--sidebar': 'oklch(0.98 0 0)' }, // single tokens, written last
+  dark: { '--sidebar': 'oklch(0.2 0 0)' },
+})
+```
+
+```sh
+npx mise-theme mise.theme.js -o src/mise-theme.css
+```
+
+Import the generated file in place of `@jovertical/mise-design-system/theme.css` (keep the
+`@source` line). Re-run the command after changing the config; in a build script,
+`emitThemeCss(config)` from `/tokens` does the same in code. `presets` and `BASES` from
+`/tokens` list the ready-made combinations.
+
+`npx --no-install mise-theme info --json` reports the config it finds as `themeConfig`.
+
+## Rules
+
+- Theme through tokens; never restyle a component's colours, radius or type through `class`.
+- Never write a palette class (`bg-teal-600`) or a `dark:` colour override in the app's UI. Both
+  bypass the theme and break the other scheme.
+- Status colour comes from `tone`, which reads `--info`, `--success`, `--warning` and
+  `--destructive` (the `critical` tone). Change the status hue in the theme, not per component.