@heyramzi/ui 2.24.0 → 3.0.0

package/src/components/toolbar/toolbar.svelte.d.ts

@@ -0,0 +1,47 @@
+import type { Snippet } from "svelte";
+import type { TabDef } from "../segmented/animated-tabs.svelte";
+declare function $$render<Tab extends string, View extends string>(): {
+    props: {
+        /** The search text. Leave it out for no search. */
+        search?: string;
+        searchPlaceholder?: string;
+        /** The label of the narrow search button. Translate at the call site. */
+        searchLabel?: string;
+        /** A strip of tabs, such as All, Open and Done. */
+        tabs?: readonly TabDef<Tab>[];
+        tab?: Tab;
+        tabsLabel?: string;
+        /** How the page shows its records: a list, a board, a grid. Each one needs an icon. */
+        views?: readonly (TabDef<View> & {
+            icon: NonNullable<TabDef<View>["icon"]>;
+        })[];
+        view?: View;
+        viewLabel?: string;
+        /** Controls that stay on the row at every width, such as filter chips. They scroll sideways before they wrap. */
+        filters?: Snippet;
+        /** The primary action and its neighbours, pinned to the right edge. */
+        actions?: Snippet;
+        class?: string;
+    };
+    exports: {};
+    bindings: "search" | "tab" | "view";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<Tab extends string, View extends string> {
+    props(): ReturnType<typeof $$render<Tab, View>>['props'];
+    events(): ReturnType<typeof $$render<Tab, View>>['events'];
+    slots(): ReturnType<typeof $$render<Tab, View>>['slots'];
+    bindings(): "search" | "tab" | "view";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <Tab extends string, View extends string>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<Tab, View>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<Tab, View>['props']>, ReturnType<__sveltets_Render<Tab, View>['events']>, ReturnType<__sveltets_Render<Tab, View>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<Tab, View>['bindings']>;
+    } & ReturnType<__sveltets_Render<Tab, View>['exports']>;
+    <Tab extends string, View extends string>(internal: unknown, props: ReturnType<__sveltets_Render<Tab, View>['props']> & {}): ReturnType<__sveltets_Render<Tab, View>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any, any>['bindings']>;
+}
+declare const $$Component: $$IsomorphicComponent;
+type $$Component<Tab extends string, View extends string> = InstanceType<typeof $$Component<Tab, View>>;
+export default $$Component;

package/src/components/toolbar/toolbar.test.ts

@@ -72,4 +72,11 @@ describe("Toolbar", () => {
     expect(root.querySelector('button[aria-label="View"]')).toBeNull();
     expect(root.querySelector('button[aria-label="Show"]')).not.toBeNull();
   });
+
+  // The 10 Nov audit: the wide search box had only its placeholder for a name.
+  it("names the wide search box with searchLabel", () => {
+    const root = render({ search: "", searchLabel: "Search clients" });
+    const box = root.querySelector(".\\@max-2xl\\/toolbar\\:hidden input");
+    expect(box?.getAttribute("aria-label")).toBe("Search clients");
+  });
 });

package/src/components/work-parts/group-head.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { Snippet } from "svelte";
+interface Props {
+    label: string;
+    /** The status colour of the dot. Leave out for no dot. */
+    hue?: string;
+    count: number;
+    /** Shows a plus at the end that adds an item to this group. */
+    onAdd?: () => void;
+    addLabel?: string;
+    /** Extra controls before the plus. */
+    children?: Snippet;
+    class?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/components/work-parts/index.ts

@@ -1,4 +1,3 @@
-export { default as CountChip } from "../chip/count-chip.svelte";
 export { default as GroupHead } from "./group-head.svelte";
 export { default as PropertyRow } from "./property-row.svelte";
 export { default as WorkCard } from "./work-card.svelte";

package/src/components/work-parts/property-row.svelte.d.ts

@@ -0,0 +1,19 @@
+import type { Component, Snippet } from "svelte";
+interface Props {
+    label: string;
+    /** A Phosphor icon before the label. */
+    icon?: Component<{
+        class?: string;
+        "aria-hidden"?: boolean | "true" | "false";
+    }>;
+    /**
+     * `responsive`: the label hides in a narrow container (a chip row) and shows as a column
+     * from `@3xl` up. `row`: always icon, label, value.
+     */
+    layout?: "row" | "responsive";
+    children: Snippet;
+    class?: string;
+}
+declare const $$Component: Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/components/work-parts/work-card.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+interface Props extends HTMLAttributes<HTMLElement> {
+    /** The bottom row: dates, subtasks, time, avatars. */
+    meta?: Snippet;
+    children: Snippet;
+    class?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/components/work-parts/work-well.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+interface Props extends HTMLAttributes<HTMLDivElement> {
+    /** Any CSS colour. Tints the well only while something is held over it. */
+    hue?: string;
+    /** Something is held over the well. */
+    active?: boolean;
+    children: Snippet;
+    class?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/css-layers.test.ts

@@ -0,0 +1,138 @@
+/*
+ * Unlayered CSS beats every layer, so one kit rule outside `@layer components` silently beats a caller's utility class.
+ * Design: ui-3.0 plan, section 1.
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse, parseCss } from "svelte/compiler";
+import type { AST } from "svelte/compiler";
+import { describe, expect, it } from "vite-plus/test";
+
+const src = dirname(fileURLToPath(import.meta.url));
+
+const ORDER = "theme, base, components, utilities";
+
+/** Top-level at-rules that hold no style rules of their own, or that Tailwind and Svelte need at the top. */
+const TOP_LEVEL_AT_RULES = new Set([
+  "layer",
+  "keyframes",
+  "-webkit-keyframes",
+  "property",
+  "theme",
+  "utility",
+  "custom-variant",
+  "import",
+  "source",
+  "font-face",
+]);
+
+/** Kit stylesheets that keep top-level rules, and why. */
+const UNLAYERED_FILES: Record<string, string> = {
+  "tokens/palette.css": "token blocks that agency-os and upsys scripts read by top-level selector",
+  "tokens/craft.css": "token blocks that agency-os and upsys scripts read by top-level selector",
+  "tokens/primitives.css": "reached only through tokens/index.css, which declares the order",
+  "shadcn/utilities.css": "its reduced-motion `.shimmer` rule has to beat the `shimmer` utility",
+};
+
+/** Component rules that stay unlayered because a utility on the same element would beat them, and why. */
+const UNLAYERED_RULES: Record<string, string> = {
+  "work/kanban-hidden-rail.svelte .kanban-rail-item-leaving":
+    "the row's `transition-[background-color,outline-color]` utility would drop the fade out",
+  "work/time/time-tracker.svelte .time-chip.is-running :global(.time-open)":
+    "the ghost button's `hover:text-foreground` would drop the running accent",
+};
+
+function keptUnlayered(file: string, css: string, node: Node): boolean {
+  const all = rules(node);
+  return (
+    all.length > 0 &&
+    all.every(
+      (rule) =>
+        `${file} ${css.slice(rule.prelude.start, rule.prelude.end).trim()}` in UNLAYERED_RULES,
+    )
+  );
+}
+
+function files(dir: string, ext: string): string[] {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) return files(path, ext);
+    return entry.name.endsWith(ext) ? [path] : [];
+  });
+}
+
+type Node = AST.CSS.Rule | AST.CSS.Atrule;
+
+function rules(node: Node): AST.CSS.Rule[] {
+  if (node.type === "Rule") return [node];
+  return (node.block?.children ?? []).flatMap((child) =>
+    child.type === "Declaration" ? [] : rules(child),
+  );
+}
+
+/** xyflow's own stylesheet is unlayered, so a canvas rule on its parts stays unlayered to keep winning. */
+function overridesXyflow(file: string, css: string, node: Node): boolean {
+  if (!file.startsWith("canvas/")) return false;
+  const all = rules(node);
+  return (
+    all.length > 0 &&
+    all.every((rule) => css.slice(rule.prelude.start, rule.prelude.end).includes("svelte-flow"))
+  );
+}
+
+/** Every reason this stylesheet's top level lets a rule escape the components layer. */
+function violations(file: string, css: string): string[] {
+  const nodes = parseCss(css).children;
+  const found: string[] = [];
+  const line = (node: Node) => `${file}:${css.slice(0, node.start).split("\n").length}`;
+
+  for (const node of nodes) {
+    if (overridesXyflow(file, css, node) || keptUnlayered(file, css, node)) continue;
+    if (node.type === "Rule") {
+      found.push(`${line(node)} rule outside a layer`);
+    } else if (!TOP_LEVEL_AT_RULES.has(node.name)) {
+      const reducedMotion =
+        file === "tokens/base.css" && node.prelude.includes("prefers-reduced-motion");
+      if (!reducedMotion) found.push(`${line(node)} @${node.name} outside a layer`);
+    }
+  }
+
+  const layered = nodes.some(
+    (node) => node.type === "Atrule" && node.name === "layer" && node.block,
+  );
+  const first = nodes[0];
+  const declaresOrder =
+    first?.type === "Atrule" &&
+    first.name === "layer" &&
+    !first.block &&
+    first.prelude.replace(/\s+/g, " ").trim() === ORDER;
+  if (layered && !declaresOrder)
+    found.push(`${file} has a layer block but doesn't open with @layer ${ORDER};`);
+  return found;
+}
+
+function styleBlock(path: string): string | null {
+  return parse(readFileSync(path, "utf8"), { modern: true }).css?.content.styles ?? null;
+}
+
+describe("kit CSS sits in the components layer", () => {
+  it("in every stylesheet", () => {
+    const found = files(src, ".css").flatMap((path) => {
+      const file = relative(src, path);
+      return file in UNLAYERED_FILES ? [] : violations(file, readFileSync(path, "utf8"));
+    });
+    expect(found).toEqual([]);
+  });
+
+  it("in every component style block", () => {
+    const found = files(src, ".svelte").flatMap((path) => {
+      const file = relative(src, path);
+      const css = styleBlock(path);
+      if (css === null) return [];
+      return violations(file, css);
+    });
+    expect(found).toEqual([]);
+  });
+});

package/src/editor/README.md

@@ -28,7 +28,7 @@ pnpm add @heyramzi/ui
   let doc = $state<Record<string, unknown> | null>(null);
 </script>
 
-<RichEditor content={doc} onchange={(json) => (doc = json)} preset="full" />
+<RichEditor content={doc} onContentChange={(json) => (doc = json)} preset="full" />
 
 <RichRenderer content={doc} />
 ```

package/src/editor/block-move.test.ts

@@ -0,0 +1,58 @@
+import { afterEach, describe, expect, it } from "vite-plus/test";
+import { Editor } from "@tiptap/core";
+import { StarterKit } from "@tiptap/starter-kit";
+import { TextSelection } from "@tiptap/pm/state";
+import { moveBlock } from "./block-move.js";
+
+let editor: Editor | null = null;
+
+afterEach(() => {
+  editor?.destroy();
+  editor = null;
+});
+
+function make(html: string) {
+  editor = new Editor({ extensions: [StarterKit], content: html });
+  return editor;
+}
+
+const texts = (e: Editor) => e.state.doc.content.content.map((n) => n.textContent);
+
+/** Puts the cursor `offset` characters into top-level block `index`. */
+function cursorIn(e: Editor, index: number, offset: number) {
+  let pos = 0;
+  for (let i = 0; i < index; i++) pos += e.state.doc.child(i).nodeSize;
+  e.view.dispatch(e.state.tr.setSelection(TextSelection.create(e.state.doc, pos + 1 + offset)));
+}
+
+describe("moveBlock", () => {
+  it("swaps the cursor's block with the one below and keeps the cursor in it", () => {
+    const e = make("<p>alpha</p><p>beta</p><p>gamma</p>");
+    cursorIn(e, 0, 2);
+    const tr = moveBlock(e.state, 1);
+    if (!tr) throw new Error("expected a move");
+    e.view.dispatch(tr);
+    expect(texts(e)).toEqual(["beta", "alpha", "gamma"]);
+    expect(e.state.selection.$from.parent.textContent).toBe("alpha");
+    expect(e.state.selection.$from.parentOffset).toBe(2);
+  });
+
+  it("moves a whole list up as one block", () => {
+    const e = make("<p>intro</p><ul><li><p>one</p></li><li><p>two</p></li></ul>");
+    cursorIn(e, 1, 3);
+    const tr = moveBlock(e.state, -1);
+    if (!tr) throw new Error("expected a move");
+    e.view.dispatch(tr);
+    expect(e.state.doc.child(0).type.name).toBe("bulletList");
+    // StarterKit keeps an empty paragraph after a closing list, so only the first two are ours.
+    expect(texts(e).slice(0, 2)).toEqual(["onetwo", "intro"]);
+  });
+
+  it("does nothing at the top or bottom", () => {
+    const e = make("<p>alpha</p><p>beta</p>");
+    cursorIn(e, 0, 0);
+    expect(moveBlock(e.state, -1)).toBeNull();
+    cursorIn(e, 1, 0);
+    expect(moveBlock(e.state, 1)).toBeNull();
+  });
+});

package/src/editor/block-move.ts

@@ -0,0 +1,52 @@
+import { Extension } from "@tiptap/core";
+import { Fragment } from "@tiptap/pm/model";
+import {
+  NodeSelection,
+  Selection,
+  TextSelection,
+  type EditorState,
+  type Transaction,
+} from "@tiptap/pm/state";
+
+/**
+ * Swaps the top-level block holding the selection with its neighbour, the same block the drag
+ * handle moves. Null at the top or bottom of the document.
+ */
+export function moveBlock(state: EditorState, dir: -1 | 1): Transaction | null {
+  const { selection, doc } = state;
+  const index = selection.$from.index(0);
+  const other = index + dir;
+  if (other < 0 || other >= doc.childCount) return null;
+
+  const node = doc.child(index);
+  const start = selection.$from.posAtIndex(index, 0);
+  const neighbour = doc.child(other);
+  const from = dir === 1 ? start : start - neighbour.nodeSize;
+  const to = from + node.nodeSize + neighbour.nodeSize;
+  const pair = dir === 1 ? [neighbour, node] : [node, neighbour];
+  const tr = state.tr.replaceWith(from, to, Fragment.fromArray(pair));
+
+  const moved = dir === 1 ? from + neighbour.nodeSize : from;
+  const shift = moved - start;
+  const next =
+    selection instanceof NodeSelection
+      ? NodeSelection.create(tr.doc, selection.from + shift)
+      : selection instanceof TextSelection
+        ? TextSelection.create(tr.doc, selection.anchor + shift, selection.head + shift)
+        : Selection.near(tr.doc.resolve(selection.head + shift));
+  return tr.setSelection(next).scrollIntoView();
+}
+
+/** Alt+Shift+Up and Down: the keyboard way to do what the drag handle does. */
+export const BlockMove = Extension.create({
+  name: "blockMove",
+  addKeyboardShortcuts() {
+    const run = (dir: -1 | 1) => () => {
+      const tr = moveBlock(this.editor.state, dir);
+      if (!tr) return false;
+      this.editor.view.dispatch(tr);
+      return true;
+    };
+    return { "Alt-Shift-ArrowUp": run(-1), "Alt-Shift-ArrowDown": run(1) };
+  },
+});