@preset.nz/facets 0.1.3 → 0.3.0

package/src/file-handlers.ts

@@ -0,0 +1,158 @@
+import { useEffect, useRef, useState } from "react"
+import type { FileFieldDef, FileFilter } from "./types"
+
+/** What the user chose in the file field's context menu. */
+export type FileMenuChoice = "reveal" | "clear"
+
+/**
+ * The native half of the `file` field, supplied by the host so facets depends on neither Tauri
+ * nor app-kit. app-kit's functions have exactly these shapes: `recent: recentPaths`,
+ * `remember: rememberPath`, `pick: pickFile`, `exists: pathsExist`, `reveal: revealPath`,
+ * `contextMenu: pathFieldMenu`. Every member is optional; a field uses what the host gave it
+ * and is a plain editable text field when it gave none.
+ */
+export interface FileHandlers {
+  /** The recent paths of a field kind (`recentKey`), newest first. Feeds the ▾ list. */
+  recent?: (key: string) => Promise<string[]>
+  /**
+   * Put a path at the top of a kind's recent list. Called once the host has accepted a commit
+   * (the field's value became the committed path), never for a refused one.
+   */
+  remember?: (key: string, path: string) => void | Promise<void>
+  /** The native Open dialog: the absolute path chosen, or null when cancelled. Feeds the browse icon. */
+  pick?: (opts: { filters?: FileFilter[]; title?: string }) => Promise<string | null>
+  /**
+   * Whether each path exists, in order. Relative paths resolve against `base`. Gone recents are
+   * left out of the ▾ list, and the current value shows Missing; both are re-checked when the
+   * window regains focus.
+   */
+  exists?: (paths: string[], base?: string) => Promise<boolean[]>
+  /** Show the file in the Finder. */
+  reveal?: (path: string, base?: string) => void | Promise<void>
+  /**
+   * A native menu at the pointer (Reveal in Finder, Clear). Resolves to the choice, or null when
+   * dismissed. Without it the field has no context menu of its own.
+   */
+  contextMenu?: (opts: { missing: boolean; canClear?: boolean }) => Promise<FileMenuChoice | null>
+  /** The folder relative paths resolve against: the document's. Read when a field checks or reveals. */
+  base?: () => string | undefined
+}
+
+let handlers: FileHandlers | null = null
+const listeners = new Set<() => void>()
+
+/**
+ * Register the host's file handlers, once at startup (like `registerFieldRenderer`): every `file`
+ * field in every panel then works the same way. Pass `null` to remove them. Replaces any earlier
+ * registration; fields already drawn pick the change up.
+ */
+export function registerFileHandlers(next: FileHandlers | null): void {
+  handlers = next
+  for (const l of listeners) l()
+}
+
+export function getFileHandlers(): FileHandlers | null {
+  return handlers
+}
+
+/** The registered handlers, re-read if they are registered again while the field is drawn. */
+export function useFileHandlers(): FileHandlers | null {
+  const [, bump] = useState(0)
+  useEffect(() => {
+    const l = () => bump((n) => n + 1)
+    listeners.add(l)
+    return () => {
+      listeners.delete(l)
+    }
+  }, [])
+  return handlers
+}
+
+/**
+ * The Open dialog's filters for a field: `filters`, else the extensions in the deprecated
+ * `accept` (`".png,.jpg,image/*"` gives one "Files" filter of png and jpg), else none.
+ */
+export function filtersOf(
+  field: Pick<FileFieldDef, "filters" | "accept">,
+): FileFilter[] | undefined {
+  if (field.filters?.length) return field.filters
+  const extensions = (field.accept ?? "")
+    .split(",")
+    .map((t) => t.trim())
+    .filter((t) => /^\.[^./\\*]+$/.test(t))
+    .map((t) => t.slice(1))
+  return extensions.length ? [{ name: "Files", extensions }] : undefined
+}
+
+/**
+ * Whether the path is gone: false until the check says so, re-run when the path or base changes
+ * and whenever the window regains focus, so a file put back recovers without a click. Always
+ * false without an `exists` handler or a path.
+ */
+export function useMissing(path: string | null, h: FileHandlers | null): boolean {
+  const [missing, setMissing] = useState(false)
+  const exists = h?.exists
+  const base = h?.base?.()
+  useEffect(() => {
+    if (!exists || !path) {
+      setMissing(false)
+      return
+    }
+    let live = true
+    const check = () =>
+      exists([path], base).then(
+        (found) => live && setMissing(found[0] === false),
+        () => {},
+      )
+    void check()
+    window.addEventListener("focus", check)
+    return () => {
+      live = false
+      window.removeEventListener("focus", check)
+    }
+  }, [exists, path, base])
+  return missing
+}
+
+/**
+ * The ▾ list: the host's recent paths for a key with the gone ones left out (all of them when
+ * the host has no `exists`). Loaded on mount, whenever `refreshOn` changes and when the window
+ * regains focus. Returns the list and a function that reloads it.
+ */
+export function useRecent(
+  key: string | undefined,
+  h: FileHandlers | null,
+  refreshOn: unknown,
+): [string[], () => Promise<void>] {
+  const [list, setList] = useState<string[]>([])
+  const recent = h?.recent
+  const exists = h?.exists
+  const base = h?.base?.()
+  const latest = useRef(0)
+  const reload = useRef<() => Promise<void>>(async () => {})
+  reload.current = async () => {
+    if (!recent || !key) {
+      setList([])
+      return
+    }
+    const ticket = ++latest.current
+    try {
+      const all = await recent(key)
+      const found = exists && all.length ? await exists(all, base) : undefined
+      if (ticket === latest.current) setList(found ? all.filter((_, i) => found[i] !== false) : all)
+    } catch {
+      if (ticket === latest.current) setList([])
+    }
+  }
+  // biome-ignore lint/correctness/useExhaustiveDependencies: reload is read through the ref; these are what should trigger it
+  useEffect(() => {
+    void reload.current()
+    const onFocus = () => void reload.current()
+    window.addEventListener("focus", onFocus)
+    return () => {
+      window.removeEventListener("focus", onFocus)
+      latest.current++
+    }
+  }, [key, recent, exists, base, refreshOn])
+  return [list, () => reload.current()]
+}

package/src/index.ts

@@ -1,10 +1,19 @@
-export * from "./types"
+export { FieldShell, ReadOnlyText, registerBuiltinRenderers } from "./field-renderers"
 export {
-  registerScope,
-  unregisterScope,
+  type FileHandlers,
+  type FileMenuChoice,
+  filtersOf,
+  getFileHandlers,
+  registerFileHandlers,
+} from "./file-handlers"
+export { COLUMN_ROW, useLabelLayout } from "./layout"
+export { schemaProblems } from "./pages"
+export { isDisabled, PropertyPanel, promotedFields, showsIn } from "./panel"
+export {
+  getFieldRenderer,
   getScope,
   registerFieldRenderer,
-  getFieldRenderer,
+  registerScope,
+  unregisterScope,
 } from "./registry"
-export { PropertyPanel } from "./panel"
-export { registerBuiltinRenderers } from "./field-renderers"
+export * from "./types"

package/src/layout.ts

@@ -0,0 +1,41 @@
+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`
+
+/** A field's help in `"column"` layout: the same columns, the text under the control. */
+export const HELP_ROW = `grid grid-cols-[var(${LABEL_WIDTH_VAR})_minmax(0,1fr)] 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`
+}

package/src/pages.ts

@@ -0,0 +1,50 @@
+import type { PropertySchema } from "./types"
+
+/**
+ * What the JSON Schema can't say about pages and advanced groups, since it
+ * needs one part of the schema checked against another. An empty list means
+ * the schema is sound. `registerScope` throws on any problem, so a bad schema
+ * fails where it is registered rather than drawing a page with nothing on it.
+ *
+ * - `pages`, when present, is not empty and its ids are unique.
+ * - With pages, every group names a declared page; without, none names one.
+ * - Every page, including the one page of a schema without `pages`, has a group
+ *   that isn't `advanced`. A schema with no groups at all is fine.
+ */
+export function schemaProblems(schema: PropertySchema): string[] {
+  const problems: string[] = []
+  const at = (i: number) => `groups[${i}] ("${schema.groups[i].id}")`
+  const pages = schema.pages
+  if (!pages) {
+    schema.groups.forEach((g, i) => {
+      if (g.page !== undefined)
+        problems.push(`${at(i)}: names page "${g.page}", but there are no pages`)
+    })
+    if (schema.groups.length > 0 && schema.groups.every((g) => g.advanced)) {
+      problems.push("every group is advanced: the panel would show only a closed Advanced row")
+    }
+    return problems
+  }
+  if (pages.length === 0) problems.push("pages is empty: omit it for one page")
+  const ids = new Set<string>()
+  for (const p of pages) {
+    if (p.id === "") {
+      problems.push("pages: an id is empty")
+      continue
+    }
+    if (ids.has(p.id)) problems.push(`pages: "${p.id}" is declared twice`)
+    ids.add(p.id)
+  }
+  schema.groups.forEach((g, i) => {
+    if (g.page === undefined) problems.push(`${at(i)}: names no page`)
+    else if (!ids.has(g.page)) problems.push(`${at(i)}: page "${g.page}" is not declared`)
+  })
+  for (const id of ids) {
+    const groups = schema.groups.filter((g) => g.page === id)
+    if (groups.length === 0) problems.push(`page "${id}" has no groups`)
+    else if (groups.every((g) => g.advanced)) {
+      problems.push(`page "${id}" has only advanced groups: give it one that isn't`)
+    }
+  }
+  return problems
+}