neba 1.9.0 → 1.11.0

package/dist/types.d.ts

@@ -72,6 +72,20 @@ export type NebaCorner = 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end'
  * The pickers default it from the locale, so it is rarely written down at all.
  */
 export type NebaWeekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * Which unit a date picker is actually asking for.
+ *
+ * A calendar already draws three grids — days, months, years — and until now
+ * two of them were only a way of reaching the third. This says which one the
+ * reader is allowed to stop on, and therefore what the value stands for: one
+ * day, one whole month, one whole year.
+ *
+ * A coarser granularity is not a different value type. The value stays a `Date`
+ * and is normalised to the first instant of the unit chosen — the 1st of the
+ * month, the 1st of January — because a month picker that reported the 15th
+ * would be reporting a day nobody chose.
+ */
+export type NebaDateGranularity = 'day' | 'month' | 'year';
 /**
  * The viewport widths the layout components branch on, smallest first.
  *
@@ -482,3 +496,62 @@ export interface NebaStyleProps {
     /** @default 'default' */
     density?: NebaDensity;
 }
+/**
+ * Class names for the parts of a component that its `className` cannot reach.
+ *
+ * A component that draws one element needs none of this: `className` lands on
+ * that element and there is nothing else to say. A component that draws six —
+ * a field with a label, a shell, a control and two lines of text under it — has
+ * five parts a caller can see, can want to change, and has no way to name. That
+ * is what this is for, and it is the whole of what it is for.
+ *
+ * **There is never a `root` key.** `className` is the root, on every component
+ * in the library, and a `classNames.root` beside it would be a second spelling
+ * of an idea that already has one. The rule that keeps `size` meaning one thing
+ * applies here too.
+ *
+ * A slot name is a promise about the element behind it, so the union each
+ * component declares is deliberately short. Only parts that are *structurally*
+ * there — a label is a label whatever the field is — get a name; the wrappers
+ * that exist to hold a flex direction do not, because naming one freezes a
+ * layout decision into the public API.
+ */
+export type NebaSlots<Slot extends string> = Partial<Record<Slot, string>>;
+/**
+ * Key combinations a control acts on, as a map from the combination to what it
+ * does.
+ *
+ * The combinations are written the way [Shortcut](../components/shortcut) draws
+ * them — `'Enter'`, `'Mod+Enter'`, `'Escape'` — and that is the point rather
+ * than a convenience: a key a product *shows* a reader and a key it *binds* have
+ * to be spelled the same, or the label on the screen is a claim nobody checked.
+ * `Mod` is Command on a Mac and Control everywhere else.
+ *
+ * A map rather than an `onShortcut(combination, event)`, because a caller with
+ * three shortcuts wants three functions and not a `switch`. The modifiers are
+ * matched exactly, so `Enter` and `Mod+Enter` are two entries that never both
+ * fire.
+ *
+ * It is not a replacement for `onKeyDown`, which still sees every keystroke.
+ * This is for the case a component cannot express any other way: a key the
+ * control itself already has an opinion about.
+ */
+export type NebaShortcuts<E extends Element = HTMLElement> = Record<string, (event: React.KeyboardEvent<E>) => void>;
+/**
+ * The parts every field-shaped component draws, and the reason they are one
+ * type: a `classNames.label` has to mean the label on a TextField, a Select, a
+ * Checkbox and a RadioGroup alike, exactly as a `size` of `md` means one height
+ * everywhere.
+ *
+ * - `label` — the field's own name, above it or beside it.
+ * - `control` — the thing the reader actually operates: the `<input>`, the
+ *   trigger, the tick, the track.
+ * - `description` — the helper line under it.
+ * - `error` — the message that replaces it when the field is invalid.
+ *
+ * Four rather than more, because these four are the ones that exist on all of
+ * them. A shell around the control, a popup, a chip — those are real parts, but
+ * only some fields have them, and a slot offered on a component that cannot
+ * draw it is a slot that does nothing.
+ */
+export type NebaFieldSlot = 'label' | 'control' | 'description' | 'error';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neba",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "A comprehensive React UI component library — buttons, fields, menus, dialogs, tables and much more — accessible and themeable, sharing one prop vocabulary and a translucent acrylic design language. ESM only, types included, dark mode built in.",
   "type": "module",
   "types": "dist/index.d.ts",
@@ -50,6 +50,11 @@
       "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"
+    },
     "./locales": {
       "types": "./dist/locales/index.d.ts",
       "module": "./dist/locales/index.js",