@preset.nz/facets 0.1.3 → 0.2.0

package/src/field-renderers.tsx

@@ -3,7 +3,7 @@
  * components plus a single `registerBuiltinRenderers` entry point. Splitting
  * each renderer into its own file would be over-organisation for code that
  * never hot-reloads in isolation. */
-import { useMemo } from "react"
+import { useMemo, useRef } from "react"
 import { Input } from "@/components/ui/input"
 import { Label } from "@/components/ui/label"
 import {
@@ -15,7 +15,11 @@ import {
 } from "@/components/ui/select"
 import { Checkbox } from "@/components/ui/checkbox"
 import { Separator } from "@/components/ui/separator"
+import { NumberField } from "@/components/ui/number-field"
+import { Slider } from "@/components/ui/slider"
+import { ColorField } from "@/components/ui/color-field"
 import { registerFieldRenderer } from "./registry"
+import { COLUMN_ROW, NUMBER_WIDTH, NUMBER_WIDTH_INSIDE, useLabelLayout } from "./layout"
 import type {
   CheckboxFieldDef,
   ColorFieldDef,
@@ -28,11 +32,13 @@ import type {
   TextareaFieldDef,
   FileFieldDef,
   LabelFieldDef,
+  PanelView,
   SeparatorFieldDef,
   VectorFieldDef,
 } from "./types"
 
-function ReadOnlyText({ children }: { children: React.ReactNode }) {
+/** A read-only value at the height of an editable row, so read-only and editable panels line up. */
+export function ReadOnlyText({ children }: { children: React.ReactNode }) {
   return (
     <div className="min-h-8 px-0 py-1 text-xs text-foreground tabular-nums break-all">
       {children}
@@ -44,13 +50,54 @@ function Empty() {
   return <span className="text-muted-foreground">—</span>
 }
 
-function FieldShell({
+/**
+ * A field's label and control, placed as the panel's label layout and view say. Exported so a
+ * custom renderer sits on the same label column as the built-ins.
+ */
+export function FieldShell({
   label,
+  view,
+  top,
+  above,
   children,
 }: {
   label?: string
+  view?: PanelView
+  /** In a label column: align the label to the top of a tall control. */
+  top?: boolean
+  /** The label sits above the control even in a label column (a wide control, like a vector of four). */
+  above?: boolean
   children: React.ReactNode
 }) {
+  const layout = useLabelLayout()
+  // Collapsed: one compact row, label in a fixed column beside the control.
+  if (view === "collapsed") {
+    return (
+      <div className="grid grid-cols-[5.5rem_minmax(0,1fr)] items-center gap-2">
+        <Label className="truncate text-[11px] font-medium text-muted-foreground tracking-wide">
+          {label}
+        </Label>
+        <div className="min-w-0">{children}</div>
+      </div>
+    )
+  }
+  // Column: one label column shared by the panel, the control on a common edge.
+  if (layout === "column" && !above) {
+    return (
+      <div className={top ? COLUMN_ROW.replace("items-center", "items-start") : COLUMN_ROW}>
+        <Label
+          title={label}
+          className={
+            "block truncate text-[11px] font-medium text-muted-foreground tracking-wide" +
+            (top ? " pt-2" : "")
+          }
+        >
+          {label}
+        </Label>
+        <div className="min-w-0">{children}</div>
+      </div>
+    )
+  }
   return (
     <div className="flex flex-col gap-1">
       {label && (
@@ -63,6 +110,14 @@ function FieldShell({
   )
 }
 
+/** Decimal places a step implies: 0.05 gives 2, 5 gives 0. */
+function placesOf(step: number): number {
+  const s = String(step)
+  if (s.includes("e-")) return Number(s.split("e-")[1])
+  const dot = s.indexOf(".")
+  return dot === -1 ? 0 : s.length - dot - 1
+}
+
 function formatPrimitive(value: unknown): string {
   if (value == null || value === "") return ""
   if (typeof value === "boolean") return value ? "Yes" : "No"
@@ -76,10 +131,11 @@ const TextRenderer: FieldRenderer<TextFieldDef> = ({
   value,
   disabled,
   onChange,
+  view,
 }) => {
   const display = formatPrimitive(value)
   return (
-    <FieldShell label={field.label ?? field.id}>
+    <FieldShell label={field.label ?? field.id} view={view}>
       {onChange ? (
         <Input
           aria-label={field.label ?? field.id}
@@ -104,15 +160,16 @@ const TextareaRenderer: FieldRenderer<TextareaFieldDef> = ({
   value,
   disabled,
   onChange,
+  view,
 }) => {
   const display = formatPrimitive(value)
   return (
-    <FieldShell label={field.label ?? field.id}>
+    <FieldShell label={field.label ?? field.id} view={view} top>
       {onChange ? (
         <textarea
           aria-label={field.label ?? field.id}
           value={display}
-          rows={field.rows ?? 3}
+          rows={view === "collapsed" ? 1 : (field.rows ?? 3)}
           disabled={disabled}
           placeholder={field.placeholder}
           onChange={(e) => onChange(e.target.value)}
@@ -136,37 +193,55 @@ const NumberRenderer: FieldRenderer<NumberFieldDef> = ({
   value,
   disabled,
   onChange,
+  onGestureBegin,
+  onGestureEnd,
+  onGestureCancel,
 }) => {
+  const layout = useLabelLayout()
   const num =
     typeof value === "number"
       ? value
       : value != null && value !== ""
       ? Number(value)
       : null
-  const display =
-    num != null && Number.isFinite(num) ? num.toLocaleString() : ""
-  return (
-    <FieldShell label={field.label ?? field.id}>
-      {onChange ? (
-        <Input
-          type="number"
-          aria-label={field.label ?? field.id}
-          value={num != null && Number.isFinite(num) ? String(num) : ""}
-          min={field.min}
-          max={field.max}
-          step={field.step ?? 1}
-          disabled={disabled}
-          onChange={(e) => onChange(Number(e.target.value))}
-        />
-      ) : display ? (
-        <ReadOnlyText>{display}</ReadOnlyText>
-      ) : (
-        <ReadOnlyText>
-          <Empty />
-        </ReadOnlyText>
-      )}
-    </FieldShell>
+  const finite = num != null && Number.isFinite(num)
+  const label = field.label ?? field.id
+  if (!onChange) {
+    return (
+      <FieldShell label={label}>
+        <ReadOnlyText>{finite ? num.toLocaleString() : <Empty />}</ReadOnlyText>
+      </FieldShell>
+    )
+  }
+  // The field's own label is the scrub handle, so the panel draws none beside it: in "column" and
+  // "stacked" it tells the field where to put it. Hosts that ignore labelPlacement keep it inside.
+  const placed =
+    layout === "auto"
+      ? {}
+      : {
+          labelPlacement: layout === "column" ? ("column" as const) : ("above" as const),
+          boxClassName: NUMBER_WIDTH,
+          suffix: field.suffix,
+        }
+  const input = (
+    <NumberField
+      label={label}
+      value={finite ? num : (field.min ?? 0)}
+      min={field.min}
+      max={field.max}
+      step={field.step ?? 1}
+      integer={field.integer}
+      className={layout === "auto" ? NUMBER_WIDTH_INSIDE : undefined}
+      {...placed}
+      disabled={disabled}
+      onValueChange={(next) => onChange(next)}
+      onScrubStart={onGestureBegin}
+      onScrubEnd={onGestureEnd}
+      onScrubCancel={onGestureCancel}
+    />
   )
+  // The field spans the label and control columns of a row of its own.
+  return layout === "column" ? <div className={COLUMN_ROW}>{input}</div> : input
 }
 
 const SliderRenderer: FieldRenderer<SliderFieldDef> = ({
@@ -174,22 +249,55 @@ const SliderRenderer: FieldRenderer<SliderFieldDef> = ({
   value,
   disabled,
   onChange,
+  view,
+  onGestureBegin,
+  onGestureEnd,
 }) => {
   const num = typeof value === "number" ? value : Number(value ?? 0)
+  // A drag is a pointer press that moves the value; arrow keys are plain edits.
+  const pressed = useRef(false)
+  const dragging = useRef(false)
+  const layout = useLabelLayout()
+  // With labels in a column or above, the value reads out to the right, on a shared edge.
+  const readout = layout !== "auto" && view !== "collapsed"
   return (
-    <FieldShell label={field.label ?? field.id}>
+    <FieldShell label={field.label ?? field.id} view={view}>
       {onChange ? (
-        <input
-          type="range"
-          aria-label={field.label ?? field.id}
-          value={Number.isFinite(num) ? num : (field.min ?? 0)}
-          min={field.min}
-          max={field.max}
-          step={field.step ?? 1}
-          disabled={disabled}
-          onChange={(e) => onChange(Number(e.target.value))}
-          className="w-full"
-        />
+        <div
+          className={readout ? "flex min-h-8 items-center gap-2" : "flex min-h-8 items-center"}
+          onPointerDownCapture={() => {
+            pressed.current = true
+          }}
+        >
+          <Slider
+            className="min-w-0 flex-1"
+            aria-label={field.label ?? field.id}
+            value={Number.isFinite(num) ? num : (field.min ?? 0)}
+            min={field.min}
+            max={field.max}
+            step={field.step ?? 1}
+            disabled={disabled}
+            onValueChange={(next) => {
+              if (pressed.current && !dragging.current) {
+                dragging.current = true
+                onGestureBegin?.()
+              }
+              onChange(Array.isArray(next) ? next[0] : next)
+            }}
+            onValueCommitted={() => {
+              pressed.current = false
+              if (dragging.current) {
+                dragging.current = false
+                onGestureEnd?.()
+              }
+            }}
+          />
+          {readout && (
+            <span className="w-12 shrink-0 text-right text-xs tabular-nums text-muted-foreground">
+              {Number.isFinite(num) ? num.toFixed(placesOf(field.step ?? 1)) : ""}
+            </span>
+          )}
+        </div>
       ) : (
         <ReadOnlyText>
           {Number.isFinite(num) ? num.toLocaleString() : <Empty />}
@@ -205,6 +313,7 @@ const SelectRenderer: FieldRenderer<SelectFieldDef> = ({
   disabled,
   onChange,
   ctx,
+  view,
 }) => {
   const options = useMemo(
     () => (field.optionsProvider ? field.optionsProvider(ctx) : (field.options ?? [])),
@@ -214,7 +323,7 @@ const SelectRenderer: FieldRenderer<SelectFieldDef> = ({
   const matched = options.find((o) => o.value === current)
   if (!onChange) {
     return (
-      <FieldShell label={field.label ?? field.id}>
+      <FieldShell label={field.label ?? field.id} view={view}>
         <ReadOnlyText>
           {matched ? matched.label : current ? current : <Empty />}
         </ReadOnlyText>
@@ -222,13 +331,13 @@ const SelectRenderer: FieldRenderer<SelectFieldDef> = ({
     )
   }
   return (
-    <FieldShell label={field.label ?? field.id}>
+    <FieldShell label={field.label ?? field.id} view={view}>
       <Select
         value={current}
         onValueChange={(v) => onChange(v)}
         disabled={disabled}
       >
-        <SelectTrigger>
+        <SelectTrigger className="w-full">
           {/* 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>
@@ -250,36 +359,32 @@ const ColorRenderer: FieldRenderer<ColorFieldDef> = ({
   value,
   disabled,
   onChange,
+  view,
+  onGestureBegin,
+  onGestureEnd,
 }) => {
   const hex = typeof value === "string" && value.length > 0 ? value : null
-  return (
-    <FieldShell label={field.label ?? field.id}>
-      <div className="flex items-center gap-2">
-        {hex ? (
-          <span
-            aria-hidden
-            className="inline-block size-4 shrink-0 border border-border"
-            style={{ backgroundColor: hex }}
-          />
-        ) : (
-          <span className="inline-block size-4 shrink-0 border border-dashed border-border" />
-        )}
-        {onChange ? (
-          <Input
-            type="text"
-            aria-label={field.label ?? field.id}
-            value={hex ?? ""}
-            disabled={disabled}
-            onChange={(e) => onChange(e.target.value)}
-            className="font-mono"
-          />
-        ) : (
-          <ReadOnlyText>
-            <span className="font-mono">{hex ?? <Empty />}</span>
-          </ReadOnlyText>
-        )}
-      </div>
+  const label = field.label ?? field.id
+  const layout = useLabelLayout()
+  // Collapsed rows and a label column keep the label in their column; otherwise the field draws it.
+  const inColumn = view === "collapsed" || layout === "column"
+  const picker = (
+    <ColorField
+      label={inColumn ? undefined : label}
+      value={hex}
+      presets={field.presets}
+      disabled={disabled}
+      onChange={onChange ? (next) => onChange(next ?? "") : undefined}
+      onPickStart={onGestureBegin}
+      onPickEnd={onGestureEnd}
+    />
+  )
+  return inColumn ? (
+    <FieldShell label={label} view={view}>
+      {picker}
     </FieldShell>
+  ) : (
+    picker
   )
 }
 
@@ -288,36 +393,50 @@ const CheckboxRenderer: FieldRenderer<CheckboxFieldDef> = ({
   value,
   disabled,
   onChange,
+  view,
 }) => {
   const checked = Boolean(value)
+  const layout = useLabelLayout()
   if (!onChange) {
     return (
-      <FieldShell label={field.label ?? field.id}>
+      <FieldShell label={field.label ?? field.id} view={view}>
         <ReadOnlyText>{checked ? "Yes" : "No"}</ReadOnlyText>
       </FieldShell>
     )
   }
+  // Collapsed rows and a label column keep the label in their column, like every other kind.
+  if (view === "collapsed" || layout === "column") {
+    return (
+      <FieldShell label={field.label ?? field.id} view={view}>
+        <Checkbox
+          checked={checked}
+          disabled={disabled}
+          onCheckedChange={(next) => onChange(Boolean(next))}
+        />
+      </FieldShell>
+    )
+  }
   return (
-    <div className="flex items-center gap-2">
+    // One line: the box, then its label, which toggles it.
+    <Label className="min-h-8 gap-2 text-xs text-foreground">
       <Checkbox
         checked={checked}
         disabled={disabled}
         onCheckedChange={(next) => onChange(Boolean(next))}
       />
-      {field.label && (
-        <Label className="text-xs text-foreground">{field.label}</Label>
-      )}
-    </div>
+      {field.label}
+    </Label>
   )
 }
 
 const FileRenderer: FieldRenderer<FileFieldDef> = ({
   field,
   value,
+  view,
 }) => {
   const asset = value as { name?: string } | null | undefined
   return (
-    <FieldShell label={field.label ?? field.id}>
+    <FieldShell label={field.label ?? field.id} view={view}>
       <ReadOnlyText>
         {asset?.name ? asset.name : <Empty />}
       </ReadOnlyText>
@@ -346,19 +465,29 @@ function formatComponent(
   return n.toLocaleString()
 }
 
+const AXES = ["X", "Y", "Z", "W"]
+
 const VectorRenderer: FieldRenderer<VectorFieldDef> = ({
   field,
   value,
   disabled,
   onChange,
+  view,
+  onGestureBegin,
+  onGestureEnd,
+  onGestureCancel,
 }) => {
+  const layout = useLabelLayout()
   const arity = field.components.length
   const values = toNumberArray(value, arity)
   const isInt = Boolean(field.integer)
+  // Three or more components take too much room beside a label column: the label goes above and
+  // the components spread across the full width.
+  const wide = arity >= 3
 
   if (!onChange) {
     return (
-      <FieldShell label={field.label ?? field.id}>
+      <FieldShell label={field.label ?? field.id} view={view} above={wide}>
         <div
           className="grid gap-x-3 gap-y-1"
           style={{ gridTemplateColumns: `repeat(${arity}, minmax(0, 1fr))` }}
@@ -390,48 +519,40 @@ const VectorRenderer: FieldRenderer<VectorFieldDef> = ({
   }
 
   return (
-    <FieldShell label={field.label ?? field.id}>
+    <FieldShell label={field.label ?? field.id} view={view} above={wide}>
       <div
-        className="grid gap-x-2"
+        className="grid gap-x-1"
         style={{ gridTemplateColumns: `repeat(${arity}, minmax(0, 1fr))` }}
       >
         {field.components.map((c, i) => (
-          <div key={i} className="flex flex-col gap-0.5 min-w-0">
-            {c.label && (
-              <span className="text-[10px] uppercase tracking-wide text-muted-foreground">
-                {c.label}
-              </span>
-            )}
-            <Input
-              type="number"
-              aria-label={c.label ?? `${field.id}[${i}]`}
-              value={values[i] != null ? String(values[i]) : ""}
-              min={c.min}
-              max={c.max}
-              step={c.step ?? (isInt ? 1 : 0.01)}
-              disabled={disabled}
-              onChange={(e) => {
-                const raw = e.target.value
-                const parsed = raw === "" ? null : Number(raw)
-                const next = values.slice()
-                next[i] =
-                  parsed != null && Number.isFinite(parsed)
-                    ? isInt
-                      ? Math.trunc(parsed)
-                      : parsed
-                    : null
-                onChange(next)
-              }}
-            />
-          </div>
+          <NumberField
+            key={i}
+            label={c.label ?? AXES[i] ?? String(i + 1)}
+            value={values[i] ?? c.min ?? 0}
+            min={c.min}
+            max={c.max}
+            step={c.step ?? (isInt ? 1 : 0.01)}
+            integer={isInt}
+            precision={field.precision}
+            suffix={layout === "auto" ? undefined : c.suffix}
+            disabled={disabled}
+            onValueChange={(next) => {
+              const out = values.map((v) => v ?? 0)
+              out[i] = isInt ? Math.trunc(next) : next
+              onChange(out)
+            }}
+            onScrubStart={onGestureBegin}
+            onScrubEnd={onGestureEnd}
+            onScrubCancel={onGestureCancel}
+          />
         ))}
       </div>
     </FieldShell>
   )
 }
 
-const SeparatorRenderer: FieldRenderer<SeparatorFieldDef> = ({ field }) =>
-  field.label ? (
+const SeparatorRenderer: FieldRenderer<SeparatorFieldDef> = ({ field, view }) =>
+  view === "collapsed" ? null : field.label ? (
     <div className="my-1 flex items-center gap-2">
       <span className="text-[10px] uppercase tracking-wide text-muted-foreground">
         {field.label}

package/src/index.ts

@@ -6,5 +6,6 @@ export {
   registerFieldRenderer,
   getFieldRenderer,
 } from "./registry"
-export { PropertyPanel } from "./panel"
-export { registerBuiltinRenderers } from "./field-renderers"
+export { PropertyPanel, promotedFields, showsIn } from "./panel"
+export { registerBuiltinRenderers, FieldShell, ReadOnlyText } from "./field-renderers"
+export { useLabelLayout, COLUMN_ROW } from "./layout"

package/src/layout.ts

@@ -0,0 +1,37 @@
+import { createContext, useContext } from "react"
+import type { FieldDef, LabelLayout } from "./types"
+
+/**
+ * The panel's label layout, for the built-in renderers. Context rather than a renderer prop, so
+ * custom renderers need no change; one that wants to follow the layout may read it with
+ * `useLabelLayout()`. Outside a `PropertyPanel` it is `"auto"`.
+ */
+export const LabelLayoutContext = createContext<LabelLayout>("auto")
+export const useLabelLayout = () => useContext(LabelLayoutContext)
+
+/** The CSS variable that holds the label column's width in `"column"` layout. Set on the panel root. */
+export const LABEL_WIDTH_VAR = "--facets-label-w"
+
+/** The grid every `"column"` row sits on: the label, then the control. */
+export const COLUMN_ROW = `grid min-h-8 grid-cols-[var(${LABEL_WIDTH_VAR})_minmax(0,1fr)] items-center gap-x-3`
+
+/**
+ * One width for every number field in a panel, whatever its label: the box is this wide in a label
+ * column or under a label, and `NUMBER_WIDTH_INSIDE` when the label sits inside it (the default
+ * layout, where it lines the boxes up on the right edge).
+ */
+export const NUMBER_WIDTH = "w-28"
+export const NUMBER_WIDTH_INSIDE = "w-44 ml-auto"
+
+/**
+ * One width for the whole panel: the longest label among the fields the view draws, in `ch`,
+ * kept between 8 and 16 so one long label doesn't squeeze every control. A longer label
+ * truncates, with its full text as a tooltip.
+ */
+export function labelColumnWidth(fields: FieldDef[]): string {
+  const longest = fields.reduce(
+    (n, f) => (f.kind === "separator" || f.kind === "label" ? n : Math.max(n, (f.label ?? f.id).length)),
+    0,
+  )
+  return `${Math.min(16, Math.max(8, longest))}ch`
+}