@preset.nz/facets 0.1.0 → 0.1.2

package/README.md

@@ -14,6 +14,10 @@ switch statement over your types.
 Built for image and map editors, where the same panel has to render a layer, a
 filter, a document or a tool depending on what is selected.
 
+The playground at [facets.preset.nz](https://facets.preset.nz) shows the field
+kinds, the schema as JSON, and the panel it draws, side by side. Its source is
+in `playground/`.
+
 ---
 
 ## Installing
@@ -45,6 +49,18 @@ So you need an `@/*` alias pointing at your `src/`, those five modules present,
 and Tailwind with shadcn's theme tokens (`muted-foreground`, `border` and
 friends are used throughout).
 
+The panel's own layout (group headers, rows, help text) is Tailwind classes in
+this package's source. Tailwind 4 does not scan `node_modules`, so name the
+package in your CSS. From `src/index.css`:
+
+```css
+@import "tailwindcss";
+@source "../node_modules/@preset.nz/facets/src";
+```
+
+Nothing fails when this line is missing. The build succeeds and the panel
+renders unstyled.
+
 The upside is that `facets` inherits whatever primitive library you already
 chose — Base UI, Radix, or your own — instead of dragging in a second one and
 making your panels look foreign inside your own app.
@@ -147,7 +163,7 @@ keep the mapping inside `read`, where your domain types are still in scope.
 
 ## Field kinds
 
-Nine ship built in.
+Eleven ship built in: nine that hold a value, and two that only show something.
 
 | Kind | Value | Notes |
 |---|---|---|
@@ -160,6 +176,12 @@ Nine ship built in.
 | `color` | hex string | `presets`; shows a swatch |
 | `vector` | number array | N scalars in one row — Houdini's `float3` / `int2`. `components` sets arity and per-slot label, suffix and range |
 | `file` | `{ name }` | display only |
+| `separator` | none | a horizontal rule, with `label` as an optional caption. No `path` |
+| `label` | none | static text: a hint or a sub-heading. The text is `label`. No `path` |
+
+Groups take `collapsible: true` to fold under their title, and
+`defaultCollapsed: true` to start folded. The open or closed state belongs to
+the group, so it resets when the panel remounts.
 
 ---
 

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@preset.nz/facets",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Schema-as-data property/inspector panels for React: FieldDef schemas, a scope registry, an open field-renderer registry, and a generic PropertyPanel.",
   "license": "MIT",
+  "homepage": "https://facets.preset.nz",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/preset-nz/facets.git"

package/src/field-renderers.tsx

@@ -14,6 +14,7 @@ import {
   SelectValue,
 } from "@/components/ui/select"
 import { Checkbox } from "@/components/ui/checkbox"
+import { Separator } from "@/components/ui/separator"
 import { registerFieldRenderer } from "./registry"
 import type {
   CheckboxFieldDef,
@@ -26,6 +27,8 @@ import type {
   TextFieldDef,
   TextareaFieldDef,
   FileFieldDef,
+  LabelFieldDef,
+  SeparatorFieldDef,
   VectorFieldDef,
 } from "./types"
 
@@ -226,7 +229,9 @@ const SelectRenderer: FieldRenderer<SelectFieldDef> = ({
         disabled={disabled}
       >
         <SelectTrigger>
-          <SelectValue />
+          {/* Children, not the primitive's own lookup: Base UI's Value shows
+              the raw value unless it's told the label. */}
+          <SelectValue>{matched ? matched.label : current}</SelectValue>
         </SelectTrigger>
         <SelectContent>
           {options.map((o) => (
@@ -425,7 +430,39 @@ const VectorRenderer: FieldRenderer<VectorFieldDef> = ({
   )
 }
 
+const SeparatorRenderer: FieldRenderer<SeparatorFieldDef> = ({ field }) =>
+  field.label ? (
+    <div className="my-1 flex items-center gap-2">
+      <span className="text-[10px] uppercase tracking-wide text-muted-foreground">
+        {field.label}
+      </span>
+      <Separator className="flex-1" />
+    </div>
+  ) : (
+    <Separator className="my-1" />
+  )
+
+// The same in every mode: there is nothing to edit. Greys out under
+// disabledWhen so a hint can follow the field it describes.
+const LabelRenderer: FieldRenderer<LabelFieldDef> = ({ field, disabled }) => (
+  <p
+    className={
+      "text-xs text-muted-foreground" + (disabled ? " opacity-50" : "")
+    }
+  >
+    {field.label}
+  </p>
+)
+
 export function registerBuiltinRenderers(): void {
+  registerFieldRenderer(
+    "separator",
+    SeparatorRenderer as FieldRenderer<import("./types").FieldDef>,
+  )
+  registerFieldRenderer(
+    "label",
+    LabelRenderer as FieldRenderer<import("./types").FieldDef>,
+  )
   registerFieldRenderer(
     "text",
     TextRenderer as FieldRenderer<import("./types").FieldDef>,

package/src/panel.tsx

@@ -1,4 +1,4 @@
-import { useMemo } from "react"
+import { useId, useMemo, useState } from "react"
 import { Separator } from "@/components/ui/separator"
 import { getFieldRenderer, getScope } from "./registry"
 import type {
@@ -69,23 +69,54 @@ function PropertyGroup({
   onChange?: (path: string, val: unknown) => void
   isLast: boolean
 }) {
+  // Collapsing needs a title to click. Open or closed is the group's own
+  // state; a host that wants it remembered across selections keys the panel.
+  const collapsible = Boolean(group.collapsible && group.title)
+  const [collapsed, setCollapsed] = useState(
+    collapsible && Boolean(group.defaultCollapsed),
+  )
+  const bodyId = useId()
+  const titleClass =
+    "text-[11px] font-semibold uppercase tracking-wider text-muted-foreground"
+
   return (
     <section className="flex flex-col gap-3 px-3 py-3">
       {(group.title || group.description) && (
         <header>
-          {group.title && (
-            <h3 className="text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">
-              {group.title}
-            </h3>
-          )}
-          {group.description && (
+          {group.title &&
+            (collapsible ? (
+              <h3 className={titleClass}>
+                <button
+                  type="button"
+                  aria-expanded={!collapsed}
+                  aria-controls={bodyId}
+                  onClick={() => setCollapsed((c) => !c)}
+                  className="-mx-1 flex w-[calc(100%+0.5rem)] items-center gap-1 px-1 text-left uppercase hover:text-foreground"
+                >
+                  <svg
+                    aria-hidden
+                    viewBox="0 0 16 16"
+                    className={
+                      "size-3 shrink-0 transition-transform " +
+                      (collapsed ? "-rotate-90" : "")
+                    }
+                  >
+                    <path d="M4 6l4 4 4-4" fill="none" stroke="currentColor" strokeWidth="1.5" />
+                  </svg>
+                  {group.title}
+                </button>
+              </h3>
+            ) : (
+              <h3 className={titleClass}>{group.title}</h3>
+            ))}
+          {group.description && !(collapsible && collapsed) && (
             <p className="mt-1 text-xs text-muted-foreground">
               {group.description}
             </p>
           )}
         </header>
       )}
-      <div className="flex flex-col gap-3">
+      <div id={bodyId} hidden={collapsible && collapsed} className="flex flex-col gap-3">
         {group.rows.map((row, idx) => {
           const fields = Array.isArray(row) ? row : [row]
           return (
@@ -142,11 +173,14 @@ function FieldSlot({
     return false
   })()
 
+  // Display-only kinds (separator, label) have no path: no value, no writes.
+  const path = "path" in field ? field.path : undefined
   return renderer({
     field,
-    value: values[field.path],
+    value: path === undefined ? undefined : values[path],
     disabled,
-    onChange: onChange ? (val) => onChange(field.path, val) : undefined,
+    onChange:
+      onChange && path !== undefined ? (val) => onChange(path, val) : undefined,
     ctx,
   })
 }

package/src/types.ts

@@ -9,6 +9,9 @@ export type BuiltinFieldKind =
   | "color"
   | "checkbox"
   | "file"
+  | "vector"
+  | "separator"
+  | "label"
 
 export interface BaseField {
   kind: string
@@ -109,6 +112,28 @@ export interface FileFieldDef extends BaseField {
   helperText?: string
 }
 
+// Display-only rows: they show something but hold no value, so they have no
+// `path`. Houdini's Separator and Label parameter types.
+
+/**
+ * A horizontal rule between rows, with an optional caption. Every kind keeps
+ * `label` so hosts can read `field.label` on any FieldDef without narrowing.
+ */
+export interface SeparatorFieldDef {
+  kind: "separator"
+  id: string
+  label?: string
+  disabledWhen?: DisabledWhen
+}
+
+/** Static text: a hint, a note, a sub-heading. The text is `label`. */
+export interface LabelFieldDef {
+  kind: "label"
+  id: string
+  label: string
+  disabledWhen?: DisabledWhen
+}
+
 export type BuiltinFieldDef =
   | SelectFieldDef
   | ColorFieldDef
@@ -119,6 +144,8 @@ export type BuiltinFieldDef =
   | CheckboxFieldDef
   | FileFieldDef
   | VectorFieldDef
+  | SeparatorFieldDef
+  | LabelFieldDef
 
 export type FieldDef = BuiltinFieldDef | CustomFieldDef