@preset.nz/facets 0.1.3 → 0.2.0

package/src/panel.tsx

@@ -1,9 +1,13 @@
-import { useId, useMemo, useState } from "react"
+import { createContext, useContext, useId, useMemo, useState } from "react"
 import { Separator } from "@/components/ui/separator"
 import { getFieldRenderer, getScope } from "./registry"
+import { LABEL_WIDTH_VAR, LabelLayoutContext, labelColumnWidth, useLabelLayout } from "./layout"
 import type {
   FieldDef,
+  LabelLayout,
+  PanelView,
   PropertyGroupDef,
+  PropertySchema,
   ScopeContext,
 } from "./types"
 
@@ -13,14 +17,81 @@ interface PropertyPanelProps {
   ctx: ScopeContext
   readOnly?: boolean
   emptyState?: React.ReactNode
+  /** Defaults to `"inspector"`, every field. See `PanelView`. */
+  view?: PanelView
+  /** The card's heading. Overrides the schema's `title`; neither means no heading. */
+  title?: React.ReactNode
+  /**
+   * Where labels sit in the inspector and card views: `"column"` (default since 0.2.0: one shared label column), `"auto"` (the 0.1 layout)
+   * (one shared label column) or `"stacked"` (label above). See `LabelLayout`. The collapsed view
+   * ignores it.
+   */
+  labelLayout?: LabelLayout
+  /** `"column"` only: the label column's width as a CSS length. Default: fits the longest label, 8ch to 16ch. */
+  labelWidth?: string
 }
 
-export function PropertyPanel({
+/** The scope's gesture, bound to its selection and ctx, for the field slots below. */
+interface GestureHandlers {
+  begin: (path: string) => void
+  end: (path: string) => void
+  cancel: (path: string) => void
+}
+const GestureContext = createContext<GestureHandlers | null>(null)
+
+type Row = Array<FieldDef | FieldDef[]>[number]
+
+/** Whether a field shows in a view: every field in the inspector, else only those promoted to it. */
+export function showsIn(field: FieldDef, view: PanelView): boolean {
+  return view === "inspector" || (field.promote?.includes(view) ?? false)
+}
+
+/** The fields a view draws, in schema order, with paired rows flattened. */
+export function promotedFields(schema: PropertySchema, view: PanelView): FieldDef[] {
+  return schema.groups
+    .flatMap((g) => g.rows)
+    .flatMap((row) => (Array.isArray(row) ? row : [row]))
+    .filter((f) => showsIn(f, view))
+}
+
+/** A group's rows kept to one view: fields filtered, empty rows dropped. */
+function rowsIn(rows: Row[], view: PanelView): FieldDef[][] {
+  return rows
+    .map((row) => (Array.isArray(row) ? row : [row]).filter((f) => showsIn(f, view)))
+    .filter((fields) => fields.length > 0)
+}
+
+export function PropertyPanel(props: PropertyPanelProps) {
+  const { scopeKey, selection, ctx, readOnly = false } = props
+  const gesture = getScope(scopeKey)?.gesture
+  const handlers = useMemo<GestureHandlers | null>(
+    () =>
+      readOnly || !gesture
+        ? null
+        : {
+            begin: (path) => gesture.begin(path, selection, ctx),
+            end: (path) => gesture.end(path, selection, ctx),
+            cancel: (path) => gesture.cancel?.(path, selection, ctx),
+          },
+    [readOnly, gesture, selection, ctx],
+  )
+  return (
+    <GestureContext.Provider value={handlers}>
+      <PanelBody {...props} />
+    </GestureContext.Provider>
+  )
+}
+
+function PanelBody({
   scopeKey,
   selection,
   ctx,
   readOnly = false,
   emptyState,
+  view = "inspector",
+  title,
+  labelLayout = "column",
+  labelWidth,
 }: PropertyPanelProps) {
   const scope = getScope(scopeKey)
 
@@ -40,8 +111,47 @@ export function PropertyPanel({
     ? undefined
     : (path: string, val: unknown) => scope.write!(path, val, selection, ctx)
 
+  // Collapsed: what a folded scope still shows, one compact row per field.
+  // The host draws the title bar that folds it. Nothing when nothing is
+  // promoted.
+  if (view === "collapsed") {
+    const fields = promotedFields(scope.schema, "collapsed")
+    if (fields.length === 0) return null
+    return (
+      <div className="px-3 py-2">
+        <CompactRows fields={fields} values={values} ctx={ctx} onChange={onChange} />
+      </div>
+    )
+  }
+
+  // Card: an optional heading, then the fields promoted to it, with no group
+  // chrome.
+  if (view === "card") {
+    const rows = scope.schema.groups.flatMap((g) => rowsIn(g.rows, "card"))
+    const heading = title ?? scope.schema.title
+    if (rows.length === 0 && !heading) return null
+    return (
+      <LabelLayoutContext.Provider value={labelLayout}>
+      <div className="flex flex-col" style={columnStyle(labelLayout, labelWidth, rows.flat())}>
+        {heading && (
+          <header className="border-b border-border px-3 py-2 text-xs font-semibold">
+            {heading}
+          </header>
+        )}
+        {rows.length > 0 && (
+          <div className={`flex flex-col px-3 py-3 ${rowGap(labelLayout)}`}>
+            <Rows rows={rows} values={values} ctx={ctx} onChange={onChange} view="card" />
+          </div>
+        )}
+      </div>
+      </LabelLayoutContext.Provider>
+    )
+  }
+
+  const all = scope.schema.groups.flatMap((g) => rowsIn(g.rows, "inspector")).flat()
   return (
-    <div className="flex flex-col">
+    <LabelLayoutContext.Provider value={labelLayout}>
+    <div className="flex flex-col" style={columnStyle(labelLayout, labelWidth, all)}>
       {scope.schema.groups.map((group, idx) => (
         <PropertyGroup
           key={group.id}
@@ -53,9 +163,20 @@ export function PropertyPanel({
         />
       ))}
     </div>
+    </LabelLayoutContext.Provider>
   )
 }
 
+/** The shared label width, as a style on the panel root; nothing outside `"column"`. */
+function columnStyle(layout: LabelLayout, width: string | undefined, fields: FieldDef[]) {
+  return layout === "column"
+    ? ({ [LABEL_WIDTH_VAR]: width ?? labelColumnWidth(fields) } as React.CSSProperties)
+    : undefined
+}
+
+/** Space between rows: tighter in a label column, where the rows read as a table. */
+const rowGap = (layout: LabelLayout) => (layout === "column" ? "gap-1.5" : "gap-3")
+
 function PropertyGroup({
   group,
   values,
@@ -76,6 +197,9 @@ function PropertyGroup({
     collapsible && Boolean(group.defaultCollapsed),
   )
   const bodyId = useId()
+  const layout = useLabelLayout()
+  // A closed group keeps its "collapsed" fields, as compact rows under its title.
+  const headerFields = collapsible && collapsed ? rowsIn(group.rows, "collapsed").flat() : []
   const titleClass =
     "text-[11px] font-semibold uppercase tracking-wider text-muted-foreground"
 
@@ -116,45 +240,98 @@ function PropertyGroup({
           )}
         </header>
       )}
-      <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 (
-            <div
-              key={idx}
-              className={
-                fields.length > 1 ? "grid grid-cols-2 gap-2" : undefined
-              }
-            >
-              {fields.map((f) => (
-                <FieldSlot
-                  key={f.id}
-                  field={f}
-                  values={values}
-                  ctx={ctx}
-                  onChange={onChange}
-                />
-              ))}
-            </div>
-          )
-        })}
+      {headerFields.length > 0 && (
+        <CompactRows fields={headerFields} values={values} ctx={ctx} onChange={onChange} />
+      )}
+      <div id={bodyId} hidden={collapsible && collapsed} className={`flex flex-col ${rowGap(layout)}`}>
+        <Rows
+          rows={rowsIn(group.rows, "inspector")}
+          values={values}
+          ctx={ctx}
+          onChange={onChange}
+          view="inspector"
+        />
       </div>
       {!isLast && <Separator className="mt-1" />}
     </section>
   )
 }
 
+/** One field per row, label and control side by side: the collapsed views. */
+function CompactRows({
+  fields,
+  values,
+  ctx,
+  onChange,
+}: {
+  fields: FieldDef[]
+  values: Record<string, unknown>
+  ctx: ScopeContext
+  onChange?: (path: string, val: unknown) => void
+}) {
+  return (
+    <div className="flex flex-col gap-1.5">
+      {fields.map((f) => (
+        <FieldSlot key={f.id} field={f} values={values} ctx={ctx} onChange={onChange} view="collapsed" />
+      ))}
+    </div>
+  )
+}
+
+function Rows({
+  rows,
+  values,
+  ctx,
+  onChange,
+  view,
+}: {
+  rows: FieldDef[][]
+  values: Record<string, unknown>
+  ctx: ScopeContext
+  onChange?: (path: string, val: unknown) => void
+  view: PanelView
+}) {
+  // In a label column a pair has no room for two labels: its fields take a row each.
+  const layout = useLabelLayout()
+  return rows.map((fields, idx) => (
+    <div
+      key={idx}
+      className={
+        fields.length > 1
+          ? layout === "column"
+            ? "contents"
+            : "grid grid-cols-2 gap-2"
+          : undefined
+      }
+    >
+      {fields.map((f) => (
+        <FieldSlot
+          key={f.id}
+          field={f}
+          values={values}
+          ctx={ctx}
+          onChange={onChange}
+          view={view}
+        />
+      ))}
+    </div>
+  ))
+}
+
 function FieldSlot({
   field,
   values,
   ctx,
   onChange,
+  view,
 }: {
   field: FieldDef
   values: Record<string, unknown>
   ctx: ScopeContext
   onChange?: (path: string, val: unknown) => void
+  view: PanelView
 }) {
+  const gesture = useContext(GestureContext)
   const renderer = getFieldRenderer(field.kind)
   if (!renderer) {
     console.warn("[properties] no renderer for kind:", field.kind)
@@ -181,6 +358,10 @@ function FieldSlot({
     disabled,
     onChange:
       onChange && path !== undefined ? (val) => onChange(path, val) : undefined,
+    onGestureBegin: gesture && path !== undefined ? () => gesture.begin(path) : undefined,
+    onGestureEnd: gesture && path !== undefined ? () => gesture.end(path) : undefined,
+    onGestureCancel: gesture && path !== undefined ? () => gesture.cancel(path) : undefined,
     ctx,
+    view,
   })
 }

package/src/types.ts

@@ -19,8 +19,34 @@ export interface BaseField {
   label?: string
   path: string
   disabledWhen?: DisabledWhen
+  promote?: PromoteView[]
 }
 
+/**
+ * A view a field can be promoted to, like a parm promoted to a Houdini
+ * asset's interface. `promote` lists them, each chosen on its own:
+ * `"card"` shows the field on the card; `"collapsed"` in a closed group's
+ * header and in a folded scope. Leave `promote` out and the field is
+ * inspector-only.
+ */
+export type PromoteView = "card" | "collapsed"
+
+/**
+ * How `PropertyPanel` draws a scope. `"inspector"` is every field in its
+ * groups; `"card"` the fields promoted to it, flat; `"collapsed"` the
+ * fields promoted to it, on one line.
+ */
+export type PanelView = "inspector" | "card" | "collapsed"
+
+/**
+ * Where a field's label sits, for the inspector and card views. `"auto"` (the default) is the
+ * original layout: number and vector fields carry their label inside the box as the scrub
+ * handle, other fields stack it above. `"column"` puts every label in one shared column to the
+ * left, so the controls start on one edge. `"stacked"` puts every label above its control.
+ * Paired rows (`[a, b]`) draw one field per row in `"column"`.
+ */
+export type LabelLayout = "auto" | "column" | "stacked"
+
 /**
  * Disables a field based on one other field's value. Exactly one operator is
  * meant to be set; if several are, the first present in the order
@@ -74,6 +100,10 @@ export interface NumberFieldDef extends BaseField {
   min?: number
   max?: number
   step?: number
+  /** Whole numbers only: no fractional display, and a fine-step modifier never goes finer than `step`. */
+  integer?: boolean
+  /** A unit after the number, e.g. `px` or `°`. Shown when the panel's `labelLayout` is `"column"` or `"stacked"`. */
+  suffix?: string
 }
 
 export interface SliderFieldDef extends BaseField {
@@ -124,6 +154,7 @@ export interface SeparatorFieldDef {
   id: string
   label?: string
   disabledWhen?: DisabledWhen
+  promote?: PromoteView[]
 }
 
 /** Static text: a hint, a note, a sub-heading. The text is `label`. */
@@ -132,6 +163,7 @@ export interface LabelFieldDef {
   id: string
   label: string
   disabledWhen?: DisabledWhen
+  promote?: PromoteView[]
 }
 
 export type BuiltinFieldDef =
@@ -161,6 +193,8 @@ export interface PropertyGroupDef {
 
 export interface PropertySchema {
   version: number
+  /** What the scope is called, e.g. "Filter". Heads the card; `PropertyPanel`'s `title` overrides it. */
+  title?: string
   groups: PropertyGroupDef[]
 }
 
@@ -177,6 +211,20 @@ export interface Scope<S = unknown, V = Record<string, unknown>> {
     selection: S,
     ctx: ScopeContext,
   ) => void
+  /**
+   * One drag as one undo step. A drag is a scrubbed number, a dragged slider
+   * thumb or an open colour picker; `begin` fires when it starts, every
+   * `write` until `end` is part of it, and `end` closes it. `cancel` fires
+   * instead of `end` when the user abandons it (Escape during a scrub): put
+   * the value back. Omit `gesture` and drags are plain repeated `write`s.
+   */
+  gesture?: ScopeGesture<S>
+}
+
+export interface ScopeGesture<S = unknown> {
+  begin: (path: string, selection: S, ctx: ScopeContext) => void
+  end: (path: string, selection: S, ctx: ScopeContext) => void
+  cancel?: (path: string, selection: S, ctx: ScopeContext) => void
 }
 
 export interface FieldRendererProps<F extends FieldDef = FieldDef> {
@@ -184,7 +232,21 @@ export interface FieldRendererProps<F extends FieldDef = FieldDef> {
   value: unknown
   disabled: boolean
   onChange?: (next: unknown) => void
+  /**
+   * A drag began, ended, or was abandoned: see `Scope.gesture`. Set only when
+   * the scope declares `gesture` and the panel is editable. The built-in
+   * number, vector, slider and colour renderers call them around their drags;
+   * a custom renderer with a continuous control may too.
+   */
+  onGestureBegin?: () => void
+  onGestureEnd?: () => void
+  onGestureCancel?: () => void
   ctx: ScopeContext
+  /**
+   * The view the field is drawn in. In `"collapsed"` it shares a line with
+   * others, so built-ins draw compact. Optional: a renderer may ignore it.
+   */
+  view?: PanelView
 }
 
 export type FieldRenderer<F extends FieldDef = FieldDef> = React.FC<