plass-ui 1.1.0 → 1.3.0

package/dist/types.d.ts

@@ -145,6 +145,95 @@ export interface PlassStyleProps {
     /** @default 'default' */
     density?: PlassDensity;
 }
+/**
+ * The parts of a labelled control a `className` does not reach.
+ *
+ * A field is four things stacked, and only the stack itself is addressable
+ * otherwise: `className` lands on the wrapper that holds the label, the control
+ * and the two lines of text under it. That is right for the layout — a
+ * `w-full`, a margin, a grid position — and it is the wrong element for every
+ * other override a caller reaches for.
+ *
+ * `control` is the part a reader acts on: the box a `PlTextField` is typed
+ * into, the button a `PlSelect` opens, the tick, the track, the row of radios.
+ * It is the one of the four that is worth naming even when the other three are
+ * not there.
+ */
+export interface PlassFieldClassNames {
+    /** The text above the control. */
+    label?: string;
+    /** The part a reader acts on. */
+    control?: string;
+    /** The helper text below it. */
+    description?: string;
+    /** The message below it, shown when the field is invalid. */
+    error?: string;
+}
+/**
+ * Chords a control answers to, in the vocabulary `PlHotKeys` draws.
+ *
+ * The key is a shortcut written the way a key cap is written — `'Enter'`,
+ * `'Escape'`, `'Mod+Enter'`, `'Shift+Enter'` — and `Mod` resolves per platform,
+ * so one entry is ⌘ on a Mac and Ctrl everywhere else. It is deliberately the
+ * *same* string a `PlHotKeys` beside the field would print: a shortcut a
+ * component displays and a shortcut it binds have to be spelled one way, or the
+ * cap on the screen is a claim nobody checked.
+ *
+ * A chord that matches is **consumed** — the handler runs and the key goes no
+ * further, so `Escape` bound on a field does not also close the dialog around
+ * it and `Enter` does not also submit the form. That is what binding a key
+ * means, and it is why these are chords rather than letters: `hotKeys={{ a }}`
+ * is a field that cannot type an `a`.
+ */
+export type PlassHotKeys = Record<string, () => void>;
+/** The parts of a portalled surface a `className` does not reach. */
+export interface PlassPortalClassNames {
+    /**
+     * The sheet drawn over the page behind the surface — the scrim, the blur, and
+     * the thing a click outside the surface lands on.
+     */
+    backdrop?: string;
+}
+/**
+ * The twelve slots a colour family is cut into.
+ *
+ * Not a vocabulary a caller invents in: these are the names `styles.css`
+ * declares six times over, once per family, and a component reads them through
+ * its `--p-*` locals rather than by name. They are spelled out here so that
+ * `PlassToken` can be a real union rather than a string.
+ */
+export type PlassColorSlot = 'accent' | 'fill' | 'line' | 'line-hover' | 'on-solid' | 'ring' | 'soft' | 'soft-hover' | 'soft-press' | 'solid' | 'solid-to' | 'tint';
+/**
+ * Every design token a caller may set, by name.
+ *
+ * The `--p-*` locals a component writes onto itself are **not** here on
+ * purpose. Those are the library talking to itself — which family this control
+ * resolved to, what its shadow costs at this `elevation` — and a caller who
+ * sets one is setting the answer rather than the question. `color`, `variant`
+ * and `elevation` are the props that decide them.
+ */
+export type PlassToken = `--plass-${PlassColor}-${PlassColorSlot}` | `--plass-radius-${PlassSize}` | `--plass-shadow-${0 | 1 | 2 | 3 | 4}` | '--plass-shadow-ambient' | '--plass-bg-from' | '--plass-bg-to' | '--plass-blur' | '--plass-border' | '--plass-divider' | '--plass-duration' | '--plass-duration-slow' | '--plass-ease' | '--plass-fg' | '--plass-flash-on-fill' | '--plass-glass' | '--plass-glass-hover' | '--plass-glass-line' | '--plass-glass-press' | '--plass-gloss-glass' | '--plass-glow-angle' | '--plass-glow-on-fill' | '--plass-muted-fg' | '--plass-scrim' | '--plass-stripe' | '--plass-surface' | '--plass-tint-strength' | '--plass-track' | '--plass-well' | '--plass-z-portal';
+/**
+ * A set of token overrides, on its own.
+ *
+ * Not a `style` object — deliberately. The augmentation below widens
+ * `CSSProperties` to accept any `--plass-*` key, which is what makes the
+ * channel usable at all but also means a typo inside a `style` is a
+ * declaration nobody reads rather than an error. This type is not widened, so
+ * a name that is not a token fails to compile: write the theme here, once, and
+ * spread it into as many `style` props as it applies to.
+ */
+export type PlassTokens = Partial<Record<PlassToken, string | number>>;
+declare module 'react' {
+    interface CSSProperties {
+        /**
+         * A Plass design token. See `PlassToken` for the names, and
+         * [the token reference](https://plass.cdget.com/design/color) for what each
+         * one paints.
+         */
+        [token: `--plass-${string}`]: string | number | undefined;
+    }
+}
 /**
  * The six effects the `PlAnimate*` components are built out of.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plass-ui",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "A React UI component library made of glass and gradients — smooth tinted surfaces, shadows in their own colour, and light that follows the pointer. Accessible and themeable, ESM only, types included, dark mode built in.",
   "type": "module",
   "types": "dist/index.d.ts",
@@ -45,6 +45,16 @@
       "module": "./dist/types.js",
       "default": "./dist/types.js"
     },
+    "./hooks": {
+      "types": "./dist/hooks/index.d.ts",
+      "module": "./dist/hooks/index.js",
+      "default": "./dist/hooks/index.js"
+    },
+    "./provider": {
+      "types": "./dist/provider/index.d.ts",
+      "module": "./dist/provider/index.js",
+      "default": "./dist/provider/index.js"
+    },
     "./styles.css": "./dist/styles.css",
     "./tailwind.css": "./dist/tailwind.css",
     "./tokens.css": "./dist/tokens.css",
@@ -61,6 +71,12 @@
       "types": [
         "dist/types.d.ts"
       ],
+      "hooks": [
+        "dist/hooks/index.d.ts"
+      ],
+      "provider": [
+        "dist/provider/index.d.ts"
+      ],
       "*": [
         "dist/components/*/index.d.ts"
       ]