@uniflowed/ui 0.0.0-alpha.14 → 0.0.0-alpha.16

package/combobox.js

@@ -618,10 +618,10 @@ export component ComboboxOption(
  * a boundary they cannot see, and the heading is never a place the cursor can
  * land, because it is not an option.
  *
- * `children` is narrower than `Select.Group`'s `React.Node`, and the narrower
- * one is the true statement: a `group` inside a `listbox` may own options and
- * its own heading, and nothing else. `Select.Group` should say the same and
- * does not yet.
+ * `children` is the true statement rather than a `React.Node` that would take
+ * anything: a `group` inside a `listbox` may own options and its own heading,
+ * and nothing else. `Select.Group` says the same since ubugeeei-prod/uf#562 —
+ * it is the same listbox, and it took a second breaking change to get there.
  */
 export component ComboboxGroup(
   children: renders* (ComboboxOption | ComboboxGroupLabel),

package/field.js

@@ -108,6 +108,22 @@ import { withProps } from "./internal/merge-props.js";
  * `onBlur` and the constraint attributes a progressive form emits — spread onto
  * whatever element `Field.Control` renders, underneath the attributes the field
  * computes.
+ *
+ * # It is declared here and produced there
+ *
+ * `@uniflowed/form`'s `useFieldSource` builds one of these, so this type is the
+ * seam between the two packages — and it lives on this side only because the
+ * dependency can only run this way today: this package is on npm and that one
+ * is not, and `tools/release/publishable.sh` refuses a published package that
+ * depends on an unpublished one.
+ *
+ * That is backwards, and ubugeeei-prod/uf#614 says so. It stands because
+ * declaring the type twice trades a documented edge for silent drift — a
+ * `Field.Root` accepting a shape `useFieldSource` no longer produces would
+ * type-check on both sides and fail only where they meet — and because the
+ * import is type-only, so no project installing `@uniflowed/form` loads,
+ * bundles or runs any of this package. #210 is the trigger: once
+ * `@uniflowed/form` publishes, this moves there and `@uniflowed/ui` imports it.
  */
 export type FieldSource = {|
   readonly invalid: boolean,

package/index.js

@@ -39,6 +39,52 @@
 // the same components with exactly the same behaviour; the design-system layer
 // that adds uf's default styles is built *on* these, not into them.
 //
+// # What is not here, and where it went instead
+//
+// About twenty of the catalogue this package is measured against have no
+// behaviour at all. Badge, Card, Button, Input, Textarea, Label and Aspect
+// Ratio are, between them, a class list and a `<div>`. For a library whose
+// product *is* the styles that is coherent — you copy them in and you own
+// them. It is not coherent here: a `Badge` with no styles is a `<span>`, a
+// `Card` with no styles is a `<div>`, and shipping them from a package that
+// ships no styles would make this a library of empty elements. Shipping them
+// from `@uniflowed/stylex` would make *that* a component library, which its
+// own header forbids. So for a long time the answer on record was both and
+// neither, which is ubugeeei-prod/uf#298.
+//
+// The line that holds is not "styled versus headless". It is **whether the
+// thing has a decision in it**:
+//
+// - An ARIA decision, a state machine or a keyboard requirement makes it a
+//   component here, even when it renders a single element. `Progress` is one
+//   `<div>`, and it belongs, because the conditional that omits
+//   `aria-valuenow` when the amount is unknown — rather than sending
+//   `aria-valuenow={0}`, which says "nothing has happened" — is the whole
+//   component. `Toggle` and `Checkbox` are the same shape for the same reason.
+// - Anything that is only a class list belongs in `@uniflowed/stylex/preset`,
+//   which already has the right form: `buttonStyles({ tone, size })`,
+//   `cardStyles()`, `textStyles({ size, tone })` and `fieldStyles()` return
+//   `{ className }` for a caller to spread onto their own element. That is a
+//   better answer than a `<Badge>`, not a lesser one — a component wrapping a
+//   `<button>` takes away `type="submit"`, `formAction`, the ref and every
+//   attribute nobody thought to forward, and gives back a class name the
+//   caller could have written.
+//
+// This is stated rather than left as an omission, because an omission reads as
+// an oversight and the next contributor closes it with a `<Badge>`.
+// `crates/uf_lib/src/ui.rs` carries the same decision as data: those entries
+// are `Declined` with the preset functions that replace them named on each,
+// and `cargo test -p uf_lib` fails if a name there stops existing.
+//
+// Five of that twenty are not presentational and are missing rather than
+// declined — Alert, Avatar, Breadcrumb, Separator and Skeleton — each for one
+// specific reason, and the registry entry for each says which. The shortest is
+// Alert: `role="alert"` is a live region, an element already in the document
+// when the page loads announces on insertion or not at all, and a permanently
+// rendered "your trial ends soon" box carrying that role is either an
+// interruption on every page load or silence. `field.js` already makes that
+// call correctly for `Field.Error`.
+//
 // # What these components promise React
 //
 // Nothing here mutates during a render, reads a ref during a render, or depends

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/ui",
-  "version": "0.0.0-alpha.14",
+  "version": "0.0.0-alpha.16",
   "description": "Headless, accessible React components whose composition Flow checks, part of the Unified Toolchain for Flow.",
   "type": "module",
   "license": "MIT",
@@ -52,9 +52,9 @@
     "internal"
   ],
   "dependencies": {
-    "@uniflowed/core": "0.0.0-alpha.14",
-    "@uniflowed/hooks": "0.0.0-alpha.14",
-    "@uniflowed/react": "0.0.0-alpha.14"
+    "@uniflowed/core": "0.0.0-alpha.16",
+    "@uniflowed/hooks": "0.0.0-alpha.16",
+    "@uniflowed/react": "0.0.0-alpha.16"
   },
   "peerDependencies": {
     "react": ">=19"

package/select.js

@@ -822,8 +822,26 @@ export component SelectOption(
  * `Select.GroupLabel` is rendered — the same rule, and the same reason, as
  * `Menu.Group`. The arrow keys pass over the label without stopping on it,
  * because they only ever look for `role="option"`.
+ *
+ * `children` is `renders* (SelectOption | SelectGroupLabel)`, which is what a
+ * `group` inside a `listbox` may hold: options, and the heading that names
+ * them. It took `React.Node` until ubugeeei-prod/uf#562, so a `<div>` in a
+ * group was a runtime surprise — an element with no role between two options,
+ * which the arrow keys walk straight past and a screen reader reads as a stray
+ * line — rather than a type error. `Combobox.Group` has stated the constraint
+ * since #558 and this is the same listbox.
+ *
+ * No `Select.Separator`, and that is deliberate rather than an omission: a rule
+ * separates *groups*, so it belongs between them in `Select.List` — which does
+ * admit one. A separator inside a group is a rule with nothing on one side of
+ * it.
+ *
+ * **Breaking.** A caller passing anything else — a `<div>` wrapper, a fragment
+ * of their own, a component that returns options — now fails `uf check`. The
+ * fix is to hand the options to the group directly; a wrapper had no effect on
+ * what this renders, because the group's element is the one below.
  */
-export component SelectGroup(children: React.Node, ...rest: Rest) {
+export component SelectGroup(children: renders* (SelectOption | SelectGroupLabel), ...rest: Rest) {
   const base = useId();
   const [labelled, setLabelled] = useState(false);