@heyramzi/ui 2.0.1 → 2.2.0

package/src/record/types.ts

@@ -0,0 +1,299 @@
+// The view types of a client or project record. Plain data in, nothing loaded:
+// the host maps its own rows onto these and passes them down.
+import type { PhosphorIcon } from "../lib/icon-types.js";
+import type { Tone } from "../lib/tone.js";
+
+/** Where a stage sits in the pipeline. Structure, not an agency's own names. */
+export type StageCategory = "open" | "proposal" | "ongoing" | "completed" | "lost";
+
+/** One stage an agency declares. The record draws its label and tone. */
+export type StageDef = {
+  key: string;
+  label: string;
+  tone: Tone;
+  category: StageCategory;
+};
+
+/**
+ * One thing that happened. Append-only. It belongs to a project, or to a client
+ * when no project exists yet. `occurredAt` is an ISO timestamp.
+ */
+export type RecordEvent = {
+  id: string;
+  /** A registry key: `call`, `note`, `stage`, or a module's own `slug:name`. */
+  kind: string;
+  occurredAt: string;
+  title: string;
+  body?: string | null;
+  /** Money, in the currency's major unit. */
+  amount?: number | null;
+  currency?: string | null;
+  /** Who or what wrote it. The host resolves the name. */
+  actor?: string | null;
+  /** A note that changed after posting. */
+  edited?: boolean;
+  /** The kind's own declared fields, already formatted by the host for display. */
+  details?: { label: string; value: string }[];
+  /** The project it belongs to. Set in client mode, so each entry can say which. */
+  projectId?: string | null;
+  projectName?: string | null;
+  projectHref?: string | null;
+  /** Where the event's source lives: the call, the invoice, the deck. */
+  href?: string | null;
+};
+
+/** The numbers and lines one project rolls up to. The host computes them. */
+export type RecordSummary = {
+  id: string;
+  name: string;
+  href?: string;
+  stageKey: string;
+  /** Short qualifier drawn after the stage, such as a loss reason. */
+  stageDetail?: string | null;
+  /** Money, in the currency's major unit. */
+  value?: number | null;
+  currency?: string | null;
+  /** Money received, from payment events. */
+  paid?: number | null;
+  startDate?: string | null;
+  endDate?: string | null;
+  whereWeAre?: {
+    text: string;
+    /** ISO timestamp of the status event. */
+    at?: string | null;
+    actor?: string | null;
+    health?: { label: string; tone: Tone } | null;
+  } | null;
+  next?: RecordNext | null;
+  lastCallAt?: string | null;
+  lastTouchAt?: string | null;
+  progress?: { done: number; total: number } | null;
+  /** A cancelled or archived project: dropped from "active" and "next". */
+  closed?: boolean;
+};
+
+/** The next milestone, or the next dated task when there are no milestones. */
+export type RecordNext = {
+  label: string;
+  /** ISO date. */
+  date?: string | null;
+  /** ISO date, for a range. */
+  endDate?: string | null;
+  owner?: string | null;
+  href?: string | null;
+  projectId?: string | null;
+  projectName?: string | null;
+};
+
+/**
+ * Each field type with its config and value; after adding one, fix what `pnpm check` raises in
+ * `fieldRow` and `INPUT` (`fields.ts`) and `InfoList`.
+ */
+export type FieldTypes = {
+  text: { config: Record<never, never>; value: string };
+  longtext: { config: Record<never, never>; value: string };
+  choice: { config: { options: FieldOption[] }; value: string };
+  multi: { config: { options: FieldOption[] }; value: string[] };
+  money: { config: { currency?: string }; value: number };
+  date: { config: Record<never, never>; value: string };
+  url: { config: Record<never, never>; value: string };
+  email: { config: Record<never, never>; value: string };
+  timezone: { config: Record<never, never>; value: string };
+  tags: { config: TagsConfig; value: string[] };
+};
+
+export type FieldType = keyof FieldTypes;
+
+/** Where a tags field's labels come from, and whether a new one may be made. */
+export type TagsConfig = {
+  /** `"existing-values"`: every value used on this field before. Or a fixed list. */
+  options: "existing-values" | readonly string[];
+  /** Whether the "Create" row is offered. A fixed list with `false` is a closed set. */
+  allowCreate: boolean;
+  max?: number;
+};
+
+export type FieldOption = {
+  key: string;
+  label: string;
+  tone?: Tone;
+  /** Still reads on old records, cannot be picked. */
+  archived?: boolean;
+};
+
+/** What a field holds. A choice is its option key, a multi is its keys, tags are the labels. */
+export type FieldValue = string | number | string[] | null;
+
+type FieldBase = {
+  key: string;
+  label: string;
+  section?: string;
+  required?: boolean;
+  /** Shown only while another field has this value. Without `equals`, any value. */
+  showWhen?: { key: string; equals?: string | string[] };
+  placeholder?: string;
+};
+
+/** One attribute a module declares. `type` picks the config, so a field can't hold another type's. */
+export type FieldDef = {
+  [T in FieldType]: FieldBase & { type: T } & FieldTypes[T]["config"];
+}[FieldType];
+
+export type FieldSectionDef = { key: string; label: string };
+
+/** One step of the rail. A step is a milestone task. */
+export type StepDef = {
+  id: string;
+  label: string;
+  done: boolean;
+  /** Which group header it sits under, such as Sales or Delivery. */
+  group?: string;
+  /** ISO dates. Both set draws a range, one draws a day. */
+  start?: string | null;
+  end?: string | null;
+  /** Hidden from the rail, still in the edit menu. */
+  hidden?: boolean;
+  /** The label was renamed: the menu offers a reset. */
+  renamed?: boolean;
+};
+
+export type StepGroupDef = { key: string; label: string };
+
+export type StepMarker = "complete" | "current" | "late" | "pending";
+
+/** One row of an `InfoList`. The value is already formatted for display. */
+export type InfoRow = {
+  /** Names the row for a host to find it. Falls back to the label. */
+  id?: string;
+  label: string;
+  icon?: PhosphorIcon;
+  value?: string | null;
+  /** A coloured chip in place of plain text. */
+  tone?: Tone;
+  /** Chips for a multi value. Wins over `value`. */
+  chips?: { label: string; tone?: Tone }[];
+  /** What the editor starts from, when it differs from what is drawn. */
+  editValue?: string | string[] | null;
+  href?: string;
+  muted?: boolean;
+  /** `select` becomes a searchable list past seven options. */
+  input?: "text" | "longtext" | "select" | "multi" | "date" | "number" | "url" | "email" | "tags";
+  options?: { value: string; label: string; tone?: Tone }[];
+  /** For `tags`: the labels to pick from, and whether a new one may be made. */
+  tags?: { options: readonly string[]; allowCreate: boolean; max?: number };
+  placeholder?: string;
+  required?: boolean;
+  /** Without it the row is read-only. A multi row passes the picked keys. */
+  onSave?: (value: string | string[]) => void | Promise<void>;
+  divider?: boolean;
+};
+
+/** A kind of event: how its filter chip and its default row read. */
+export type RecordKindDef = {
+  key: string;
+  label: string;
+  icon?: PhosphorIcon;
+  tone?: Tone;
+};
+
+/** A filter chip: a label over the kinds it shows. */
+export type RecordFilterDef = { key: string; label: string; kinds: string[] };
+
+export type RecordLabels = {
+  whereWeAre: string;
+  more: string;
+  less: string;
+  next: string;
+  late: string;
+  steps: string;
+  stepsCount: (done: number, total: number) => string;
+  editSteps: string;
+  rename: string;
+  resetName: string;
+  hide: string;
+  show: string;
+  moveUp: string;
+  moveDown: string;
+  shownCount: (shown: number, total: number) => string;
+  openSteps: string;
+  activity: string;
+  all: string;
+  noEvents: string;
+  older: (count: number) => string;
+  today: string;
+  yesterday: string;
+  by: (name: string) => string;
+  projects: string;
+  projectCount: (count: number) => string;
+  noProjects: string;
+  details: string;
+  edit: (field: string) => string;
+  add: (field: string) => string;
+  save: string;
+  cancel: string;
+  search: string;
+  noMatch: string;
+  pipeline: string;
+  won: string;
+  paid: string;
+  lastCall: string;
+  lastTouch: string;
+  noCall: string;
+  open: string;
+  edited: string;
+  noSteps: string;
+  saveFailed: string;
+  required: string;
+};
+
+export const DEFAULT_RECORD_LABELS: RecordLabels = {
+  whereWeAre: "Where we are",
+  more: "More",
+  less: "Less",
+  next: "Next",
+  late: "Late",
+  steps: "Steps",
+  stepsCount: (done, total) => `${done}/${total}`,
+  editSteps: "Choose visible steps",
+  rename: "Rename",
+  resetName: "Reset name",
+  hide: "Hide",
+  show: "Show",
+  moveUp: "Move up",
+  moveDown: "Move down",
+  shownCount: (shown, total) => `${shown} of ${total} shown`,
+  openSteps: "Open steps",
+  activity: "Activity",
+  all: "All",
+  noEvents: "Nothing logged yet",
+  older: (count) => `Show ${count} older`,
+  today: "Today",
+  yesterday: "Yesterday",
+  by: (name) => `by ${name}`,
+  projects: "Projects",
+  projectCount: (count) => (count === 1 ? "1 project" : `${count} projects`),
+  noProjects: "No projects",
+  details: "Details",
+  edit: (field) => `Edit ${field}`,
+  add: (field) => `Add ${field.toLowerCase()}`,
+  save: "Save",
+  cancel: "Cancel",
+  search: "Search",
+  noMatch: "No match",
+  pipeline: "Pipeline",
+  won: "Won",
+  paid: "Paid",
+  lastCall: "Last call",
+  lastTouch: "Last touch",
+  noCall: "None yet",
+  open: "Open",
+  edited: "edited",
+  noSteps: "No steps yet",
+  saveFailed: "Couldn't save",
+  required: "Required",
+};
+
+/** Merge a partial label set over the defaults. */
+export function resolveLabels(labels?: Partial<RecordLabels>): RecordLabels {
+  return labels ? { ...DEFAULT_RECORD_LABELS, ...labels } : DEFAULT_RECORD_LABELS;
+}

package/src/record/where-we-are.svelte

@@ -0,0 +1,125 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import { NavigationArrow } from "phosphor-svelte";
+	import { cn } from "../lib/utils.js";
+	import { Button } from "../shadcn/button/index.js";
+	import StatusBadge from "../status/status-badge.svelte";
+	import type { Tone } from "../lib/tone.js";
+	import { gutterClass } from "./gutter.js";
+	import { formatAge } from "./format.js";
+	import { resolveLabels, type RecordLabels } from "./types.js";
+
+	// =========================
+	// PROPS
+	// =========================
+	interface Props {
+		/** The status note. Nothing draws without it. */
+		note?: string | null;
+		/** ISO timestamp of the note. */
+		at?: string | null;
+		actor?: string | null;
+		health?: { label: string; tone: Tone } | null;
+		/** Client mode: the project this note belongs to. */
+		project?: { name: string; href?: string | null } | null;
+		labels?: Partial<RecordLabels>;
+		locale?: string;
+		now?: Date | number;
+		class?: string;
+	}
+	let { note, at, actor, health, project, labels, locale, now, class: className }: Props = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	let expanded = $state(false);
+	let clamped = $state(false);
+	let text = $state<HTMLElement | null>(null);
+
+	// =========================
+	// DERIVED
+	// =========================
+	let t = $derived(resolveLabels(labels));
+	let age = $derived(at ? formatAge(at, now, locale) : null);
+	let hasMeta = $derived(Boolean(health || actor || age));
+
+	// =========================
+	// EFFECTS
+	// =========================
+	// Measured, not guessed from length: a note that fits two lines at 1280px
+	// overflows at 390px, and "More" shows only when text is cut.
+	$effect(() => {
+		if (!text) return;
+		const el = text;
+		const measure = () => {
+			if (!expanded) clamped = el.scrollHeight > el.clientHeight + 1;
+		};
+		measure();
+		const observer = new ResizeObserver(measure);
+		observer.observe(el);
+		return () => observer.disconnect();
+	});
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+{#if note}
+	<section
+		aria-label={t.whereWeAre}
+		class={cn(
+			"flex items-start gap-2.5 border-b border-border bg-muted/40 py-2.5",
+			gutterClass,
+			className,
+		)}
+	>
+		<NavigationArrow
+			class="mt-0.5 size-3.5 shrink-0 text-[color:var(--tone-accent,var(--color-primary))]"
+			weight="fill"
+			aria-hidden="true"
+		/>
+		<div class="min-w-0 flex-1">
+			<!-- No `title` attribute: a native tooltip would repeat the whole note
+			     over the steps list. "More" opens it in place. -->
+			<p
+				bind:this={text}
+				class={cn("text-sm leading-snug text-muted-foreground", !expanded && "line-clamp-2")}
+			>
+				<span class="font-medium text-foreground">{t.whereWeAre}</span>
+				{#if project}
+					{#if project.href}
+						<a
+							href={project.href}
+							class="font-medium text-foreground underline-offset-2 hover:underline"
+							>{project.name}</a
+						>
+					{:else}
+						<span class="font-medium text-foreground">{project.name}</span>
+					{/if}
+				{/if}
+				<span class="whitespace-pre-line">{note}</span>
+			</p>
+			{#if hasMeta}
+				<p class="mt-1 flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-muted-foreground">
+					{#if health}
+						<StatusBadge tone={health.tone} dot capitalize={false}>{health.label}</StatusBadge>
+					{/if}
+					{#if actor}<span>{t.by(actor)}</span>{/if}
+					{#if age}<span class="tabular-nums">{age}</span>{/if}
+				</p>
+			{/if}
+		</div>
+		{#if clamped || expanded}
+			<Button
+				variant="ghost"
+				size="sm"
+				class="-mr-2 shrink-0 text-muted-foreground"
+				aria-expanded={expanded}
+				onclick={() => (expanded = !expanded)}
+			>
+				{expanded ? t.less : t.more}
+			</Button>
+		{/if}
+	</section>
+{/if}

package/src/shadcn/button/button.svelte

@@ -35,7 +35,7 @@
 
 			// WHY: every height is authored for a mouse. Under a thumb, Apple's floor is 44px, so each size grows wherever a coarse pointer exists.
 
-			// WHY sm carries a hit area: 28px is under the 32px desktop floor and the 40px coarse height is under 44. The ::after box stays the same 32px (44 on coarse) square whatever the visual size, so a dense toolbar keeps its look.
+			// WHY sm carries a hit area: 28px is under the 32px desktop floor, so an ::after box keeps it 32px (44 on coarse) without changing its look.
 
 			// Icon buttons grow both axes because they have no label to widen them. any-pointer, not pointer: see the note in tokens/base.css.
 			size: {

package/src/shadcn/card/card-title.svelte

@@ -2,11 +2,7 @@
 	import type { HTMLAttributes } from "svelte/elements";
 	import { cn, type WithElementRef } from "../../lib/utils.js";
 
-	// WHY: card titles render as a div by default for backwards compatibility,
-
-	// but a page whose sections are all cards ends up with no headings below the h1, so screen readers cannot navigate it by heading (WCAG 2.4.6).
-
-	// Pass `as="h2"` on real section titles.
+	// WHY: card titles default to a div, so pass `as="h2"` on real section titles or a page of cards has no headings for screen readers (WCAG 2.4.6).
 	let {
 		ref = $bindable(null),
 		class: className,

package/src/shadcn/hooks/use-highlighted-code.svelte.ts

@@ -6,19 +6,8 @@ import {
 import type { GrammarState } from "shiki/core";
 
 /**
- * Highlights `code` in `language`. `current` holds one entry per line: a plain
- * string until the highlighter loads, then the line's tokens. Pass each one to
- * the `code` prop of a `CodeBlock.Line`.
- *
- * ```svelte
- * <script lang="ts">
- * 	const lines = useHighlightedCode(() => code, () => "json");
- * </script>
- *
- * {#each lines.current as line, index (index)}
- * 	<CodeBlock.Line code={line} />
- * {/each}
- * ```
+ * Highlights `code`. Each `current` entry is a plain string until the highlighter loads, then
+ * tokens, so pass it to `CodeBlock.Line`'s `code` prop either way.
  */
 export function useHighlightedCode(value: () => string, language: () => string) {
   let loaded = $state.raw<{

package/src/shadcn/sheet/sheet-content.svelte

@@ -29,10 +29,8 @@
 		children: Snippet;
 	} = $props();
 
-	// Side classes are plain utilities, not `data-[side=x]:` variants. An attribute
-	// variant outranks a plain class and tailwind-merge won't dedupe across
-	// modifier sets, so a caller's `sm:max-w-xl` lost to the default 384px.
-	// Plain utilities let `cn` drop the default when a caller passes its own.
+	// Plain side utilities, not `data-[side=x]:` variants, because the variant outranks a
+	// caller's `sm:max-w-xl` and tailwind-merge can't dedupe across modifier sets.
 	const SIDE_CLASS: Record<Side, string> = {
 		// h-dvh, not h-full: on iOS Safari a fixed panel sizes against the layout
 		// viewport, which is taller than the visible area, so h-full hides the footer.

package/src/shadcn/table/table-cell.svelte

@@ -19,9 +19,8 @@
 	{@render children?.()}
 </td>
 
-<!-- WHY here: a link in a cell is 20px tall, and a cell is the only place that knows it sits in a
-     row of them. On a coarse pointer the link grows a 44px box centred on it, wider when the link
-     is. A link that positions itself (a stretched row link) keeps its own box. -->
+<!-- A cell's link is 20px tall, so on a coarse pointer it grows a 44px hit box here, unless it
+     positions itself, like a stretched row link. -->
 <style>
 	@media (any-pointer: coarse) {
 		td :global(a[href]:not([class*="absolute"], [class*="fixed"], [class*="sticky"])) {

package/src/shadcn/utilities.css

@@ -1,11 +1,6 @@
-/* Tailwind utilities the shadcn Attachment and Message components rely on:
-   scroll-fade-x and scrollbar-none for Attachment.Group's snap-scroller,
-   shimmer for a processing/uploading Attachment.Title. Vendored from
-   shadcn-svelte's own tailwind.css bundle (MIT) so this package stays
-   dependency-free (docs/decisions.md, "The package stays dependency-free").
-   `no-scrollbar` is deliberately left out: consumers already define it, and
-   a duplicate @utility breaks their build. Import this file once, after
-   Tailwind, alongside `@heyramzi/ui/design`. */
+/* Utilities the shadcn Attachment and Message parts need, vendored from
+   shadcn-svelte (MIT); `no-scrollbar` stays out because consumers define it
+   and a duplicate @utility breaks their build. */
 
 @utility scrollbar-none {
   -ms-overflow-style: none;