@appinternalleads/ui 0.2.0

package/src/components/directory/DirectoryView.tsx

@@ -0,0 +1,426 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { Box, Input, MotionView, Pressable, Text } from '../../core';
+import { BlockCard, Button, Callout, SkeletonBar } from '../../ds';
+import { useDs } from '../../tokens';
+import { Spinner } from '../onboarding/shared/parts';
+import { SurfaceProvider, useMeasuredSurface, useSurface } from '../../widgets/useSurface';
+import { staggerDelay, useEntrance, useEntranceTracker } from '../../widgets/output/motion';
+import {
+  createMockAdapter, isPristine, useQueryMachine,
+  type DataAdapter, type QueryFilter, type QueryRecord,
+} from '../../runtime/query';
+import {
+  canFilter, rulesToFilters, validateDirectoryConfig,
+  type DirectoryColumn, type DirectoryConfig, type DirectoryRule, type DirectorySchema,
+} from './contract';
+
+/**
+ * **Directory — the component.** Search, narrow, page, open a record.
+ *
+ * Everything it draws comes from the schema it was handed: the row's heading is whatever column
+ * the configuration names as primary, the facets are whatever columns were configured from the
+ * discovered ones, the detail panel lists whatever columns are configured. **There is not one
+ * column name in this file**, which is the point — a Directory over a different source renders
+ * differently without a line changing here.
+ *
+ * It owns its query lifecycle through the shared runtime (`src/runtime/query`) — the same
+ * epoch-guarded, abortable machine the Output `list` renderer uses. It is *not* `list`: different
+ * family, different contract (`DirectoryConfig`/`DirectoryRule`, not an `output/1` document), and
+ * a builder places it rather than an agent emitting it.
+ *
+ * The host owns transport: either pass a `DataAdapter`, or pass `records` already read from the
+ * source and the component queries them in memory through the runtime's deterministic adapter.
+ */
+
+export type DirectoryRecord = { id: string; data: Record<string, string> };
+
+export type DirectoryViewProps = {
+  schema: DirectorySchema;
+  config: DirectoryConfig;
+  /** User-authored and agent-authored rules, in one list — provenance is the `author` field. */
+  rules?: DirectoryRule[];
+  /** The host's transport. Omit to query `records` in memory. */
+  adapter?: DataAdapter;
+  records?: DirectoryRecord[];
+  onSelect?: (id: string) => void;
+  testID?: string;
+};
+
+const chipRadius = 999;
+
+/**
+ * A chip is as wide as its value, and a value is whatever the source holds. A column of short
+ * categories gives neat pills; a column whose few distinct values are sentences gives a chip wider
+ * than the card, which the card then clips — so the chip loses its right-hand edge and its press
+ * target with it. The label is capped and truncated instead: the full value stays in `aria-label`,
+ * so a screen reader still gets all of it.
+ */
+function FacetChip({ label, on, onPress }: { label: string; on: boolean; onPress: () => void }) {
+  const { colors } = useDs();
+  return (
+    /* A facet is a chip — the one place Solarium 0.2.0 keeps the pill — and "selected" is the
+       system's coral ring on the coral-soft ground, never a solid fill. */
+    <Pressable
+      onPress={onPress} minHeight={32} radius="pill"
+      aria-pressed={on} aria-label={label}
+      style={{
+        paddingHorizontal: 12, maxWidth: '100%', flexShrink: 1, minWidth: 0,
+        backgroundColor: on ? colors.accentTint : colors.band, borderWidth: 1.5, borderColor: on ? colors.accentFill : 'transparent',
+      }}>
+      <Text numberOfLines={1}
+        style={{ fontSize: 12.5, fontWeight: '600', minWidth: 0, color: on ? colors.accentInk : colors.textPrimary }}>
+        {label}
+      </Text>
+    </Pressable>
+  );
+}
+
+function Row({
+  record, index, seen, config, columns, selectable, onOpen, last,
+}: {
+  record: QueryRecord; index: number; seen: Set<string>; config: DirectoryConfig;
+  columns: Map<string, DirectoryColumn>; selectable: boolean; onOpen: (id: string) => void; last: boolean;
+}) {
+  const { colors } = useDs();
+  const surface = useSurface();
+  const { opacity, translateY } = useEntrance(record.id, seen, { variant: 'rise', delayMs: staggerDelay(index, 70) });
+  const d = record.data ?? {};
+  const title = d[config.primaryColumn] ?? '';
+  const secondary = config.secondaryColumn ? d[config.secondaryColumn] : undefined;
+  const meta = config.metaColumn ? d[config.metaColumn] : undefined;
+  /* The extra columns a reader sees on the row: whatever is visible, minus what the heading area
+     already shows. Generated, never listed. */
+  const extra = config.visibleColumns
+    .filter(k => k !== config.primaryColumn && k !== config.secondaryColumn && k !== config.metaColumn)
+    .map(k => ({ key: k, label: columns.get(k)?.label ?? k, value: d[k] ?? '' }))
+    .filter(x => x.value !== '');
+
+  const content = (
+    <Box
+      style={{
+        minHeight: 56, paddingVertical: 10,
+        borderBottomWidth: last ? 0 : 1, borderBottomColor: colors.hairline, gap: 3,
+      }}>
+      <Box row={surface === 'web'} align={surface === 'web' ? 'center' : undefined} style={{ gap: 14 }}>
+        <Box flex={1} style={{ gap: 3, minWidth: 0 }}>
+          <Text style={{ fontSize: 13.5, lineHeight: 18, fontWeight: '600', color: colors.textPrimary }}>
+            {title}
+          </Text>
+          {secondary ? (
+            <Text numberOfLines={2} color="textSecondary" style={{ fontSize: 12, lineHeight: 17 }}>
+              {secondary}
+            </Text>
+          ) : null}
+          {extra.length ? (
+            <Box row wrap style={{ gap: 8, marginTop: 2, minWidth: 0 }}>
+              {extra.map(x => (
+                /* `minWidth: 0` is what actually makes a one-line value truncate. Without it a
+                   flex item refuses to shrink below its content, so a long cell — a description,
+                   a URL — widens the whole row past the card, which clips it: the row loses its
+                   right-hand edge instead of the value gaining an ellipsis. The column a person
+                   configured as visible could hold anything, so this is not an edge case. */
+                <Text key={x.key} color="textSecondary" numeric numberOfLines={1}
+                  style={{ fontSize: 12, lineHeight: 16, minWidth: 0, flexShrink: 1, maxWidth: '100%' }}>
+                  {`${x.label}: ${x.value}`}
+                </Text>
+              ))}
+            </Box>
+          ) : null}
+        </Box>
+        {meta ? (
+          <Text color="textSecondary" numeric numberOfLines={1}
+            style={{ fontSize: 12, lineHeight: 16, minWidth: 0, flexShrink: 1 }}>
+            {meta}
+          </Text>
+        ) : null}
+      </Box>
+    </Box>
+  );
+
+  return (
+    <MotionView role="listitem" style={{ opacity, transform: [{ translateY }] }}>
+      {selectable ? (
+        <Pressable onPress={() => onOpen(record.id)} aria-label={meta ? `${title}, ${meta}` : title}
+          style={{ width: '100%', alignItems: 'stretch' }}>
+          {content}
+        </Pressable>
+      ) : content}
+    </MotionView>
+  );
+}
+
+function Detail({
+  record, config, columns, onBack,
+}: { record: QueryRecord; config: DirectoryConfig; columns: Map<string, DirectoryColumn>; onBack: () => void }) {
+  const { colors } = useDs();
+  const d = record.data ?? {};
+  return (
+    <Box style={{ gap: 10 }}>
+      <Button variant="secondary" size="xsmall" leadingGlyph="chev-l" onPress={onBack} aria-label="Back to results">Back to results</Button>
+      <Text role="heading" aria-level={3} style={{ fontSize: 16, lineHeight: 21, fontWeight: '600', letterSpacing: -0.24 }}>{d[config.primaryColumn] ?? ''}</Text>
+      <Box role="list" style={{ gap: 0 }}>
+        {config.detailColumns.map((key, i) => {
+          const value = d[key] ?? '';
+          return (
+            <Box key={key} role="listitem"
+              style={{ paddingVertical: 10, borderTopWidth: i === 0 ? 0 : 1, borderTopColor: colors.hairline, gap: 3 }}>
+              <Text color="textSecondary" style={{ fontSize: 12, lineHeight: 15 }}>{columns.get(key)?.label ?? key}</Text>
+              {/* An empty cell is said, not skipped — "not recorded" and "blank" are different facts. */}
+              <Text style={{ fontSize: 13, lineHeight: 19, color: value ? colors.textPrimary : colors.textSecondary }}>
+                {value || 'Not recorded'}
+              </Text>
+            </Box>
+          );
+        })}
+      </Box>
+    </Box>
+  );
+}
+
+/**
+ * **A new source is a new Directory.**
+ *
+ * Everything the view holds — the search text, the chips, the sort column, the page, the open
+ * record — is expressed in the *current* schema's column keys. Carry it across a reconnection and
+ * every one of them is a key the new source has never heard of: the rows come back, the query
+ * still holds the old sheet's filter, and the headings render blank. So the source identity is a
+ * remount boundary, and the identity is the columns themselves rather than the URL, because a
+ * builder reconnecting the same sheet after a column changed is exactly the case that breaks.
+ *
+ * Deliberately *not* keyed on the configuration: editing what a reader sees must not throw away
+ * what they were looking at, which is the whole reason the builder can preview live.
+ */
+export function DirectoryView(props: DirectoryViewProps) {
+  const { source, columns } = props.schema;
+  const key = `${source.kind}|${source.url}|${source.sheetName}|${source.sheetGid ?? ''}|${JSON.stringify(columns.map(c => c.key))}`;
+  return <DirectoryBody key={key} {...props} />;
+}
+
+function DirectoryBody({ schema, config, rules = [], adapter, records = [], onSelect, testID }: DirectoryViewProps) {
+  const { surface, onLayout } = useMeasuredSurface();
+  const columns = useMemo(() => new Map(schema.columns.map(c => [c.key, c])), [schema]);
+  const configErrors = useMemo(() => validateDirectoryConfig(config, schema), [config, schema]);
+
+  /* In-memory execution over rows the host already read, through the SAME runtime adapter the
+     `list` fixtures use — so every operator here is one `applyFilter` really implements. */
+  const fallback = useMemo(
+    () => createMockAdapter({ records: records.map(r => ({ id: r.id, data: r.data })) }),
+    [records],
+  );
+  const machine = useQueryMachine(
+    {
+      resource: schema.source.sheetName,
+      searchColumns: config.searchColumns,
+      pageSize: config.pageSize,
+      initialSort: config.sort ? { column: config.sort.column, dir: config.sort.dir } : null,
+      filterableColumns: schema.columns.filter(canFilter).map(c => c.key),
+      initial: { filters: rulesToFilters(rules), search: '' },
+    },
+    adapter ?? fallback,
+  );
+
+  /* Rules are the builder's; when they change, the query changes. Agent-authored rules arrive the
+     same way — they are the same objects in the same list, compiled by the same function. Keyed on
+     the compiled filters rather than the rules so that editing a rule's id, or switching one off
+     and straight back on, does not re-run a query that would return the same rows. */
+  const ruleKey = JSON.stringify(rulesToFilters(rules));
+  const { setAgentFilters, setFilter } = machine;
+  const first = useRef(true);
+  /**
+   * The columns the rule set governed last time, so a rule that is deleted can take its filter
+   * with it.
+   *
+   * **Why this is needed.** The runtime's bulk setter drops the filters it previously installed
+   * *as the agent* and deliberately keeps user-authored ones — that is the `list` rule (N1): an
+   * agent adding a filter must never wipe out the chips a reader has pressed. A Directory rule,
+   * though, may be user-authored, so a deleted user rule's filter matched nothing to remove and
+   * stayed in the query for good: clear every rule in the builder and the preview stayed narrowed.
+   * Tracking the governed columns and clearing the ones that fall out is the smallest fix that
+   * leaves that `list` rule alone — and a reader's own chip on an ungoverned column still survives.
+   */
+  const governed = useRef<string[]>([]);
+  const lastRuleKey = useRef<string | null>(null);
+  useEffect(() => {
+    const filters = JSON.parse(ruleKey) as QueryFilter[];
+    const columns = filters.map(f => f.column);
+    if (first.current) { first.current = false; governed.current = columns; lastRuleKey.current = ruleKey; return; }
+    if (lastRuleKey.current === ruleKey) return;
+    lastRuleKey.current = ruleKey;
+    const now = new Set(columns);
+    for (const column of governed.current) if (!now.has(column)) setFilter(column, null);
+    governed.current = columns;
+    setAgentFilters(filters);
+  }, [ruleKey, setAgentFilters, setFilter]);
+
+  /**
+   * **The configured order is a default, and changing it changes the default.**
+   *
+   * `initialSort` only seeds the machine, so a builder editing the configured sort would otherwise
+   * see it ignored by a preview that is already mounted — the configuration and what is on screen
+   * would disagree, which is exactly what a live preview exists to prevent. Applied on *change*
+   * rather than on every render, so a reader's own sort choice survives an unrelated edit.
+   */
+  /* Serialised, so the effect depends on the sort's VALUE rather than on the object's identity —
+     a configuration rebuilt on every keystroke would otherwise re-sort on every keystroke. */
+  const sortKey = config.sort ? `${config.sort.column}:${config.sort.dir}` : '';
+  const { setSort } = machine;
+  const lastSort = useRef(sortKey);
+  useEffect(() => {
+    if (lastSort.current === sortKey) return;
+    lastSort.current = sortKey;
+    const [column, dir] = sortKey.split(':');
+    setSort(column ? { column, dir: dir === 'asc' ? 'asc' : 'desc' } : null);
+  }, [sortKey, setSort]);
+
+  const seen = useEntranceTracker();
+  const [text, setText] = useState('');
+  const [typing, setTyping] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => () => { if (timer.current) clearTimeout(timer.current); }, []);
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+
+  const { state } = machine;
+  const rows = state.data?.records ?? [];
+  const total = state.data?.meta.total;
+  const pageOffset = state.query.page.strategy === 'offset' ? state.query.page.offset : 0;
+  const selected = selectedId ? rows.find(r => r.id === selectedId) : undefined;
+
+  const onText = (v: string) => {
+    setText(v); setTyping(true);
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = setTimeout(() => { setTyping(false); machine.setSearch(v); }, 300);
+  };
+
+  const facets = config.filterColumns
+    .map(k => columns.get(k))
+    .filter((c): c is DirectoryColumn => !!c && canFilter(c));
+
+  /* Before any records arrive the footer says what is happening — and a failed first read is not
+     "Loading": the alert above it says what went wrong, the count says nothing was read. */
+  const counter = !state.data ? (state.status === 'error' ? 'Nothing read' : 'Loading')
+    : rows.length === 0 ? (isPristine(state.query) ? config.copy.emptyLabel : config.copy.noResultsLabel)
+    : total === undefined ? `Showing ${rows.length}`
+    : rows.length === total && pageOffset === 0 ? `${total} records`
+    : `${pageOffset + 1}–${pageOffset + rows.length} of ${total}`;
+
+  const canPrev = pageOffset > 0;
+  const canNext = total !== undefined ? pageOffset + config.pageSize < total : rows.length >= config.pageSize;
+  const sortIndex = config.sortColumns.findIndex(k => k === state.query.sort?.column);
+
+  if (configErrors.length) {
+    /* A configuration naming a column the source doesn't have is a builder error, not a blank
+       screen: it is shown as an apricot Callout, rather than rendering something misleading. */
+    return (
+      <BlockCard testID={testID} title={config.title} subtitle={config.description}>
+        <Callout title="Configuration">{configErrors.join('\n')}</Callout>
+      </BlockCard>
+    );
+  }
+
+  const busy = typing || (state.status === 'loading' && !!state.data);
+  const sortLabel = state.query.sort
+    ? `${columns.get(state.query.sort.column)?.label ?? state.query.sort.column} ${state.query.sort.dir === 'asc' ? '↑' : '↓'}`
+    : 'None';
+
+  /* The current card shell (S1): header (title, description, a spinner while it searches) · body
+     (search, facets, sort, the records) · footer (the count on the left, paging on the right). The
+     count lives in the footer's hint, as every current component's does. */
+  return (
+    <SurfaceProvider surface={surface}>
+      <Box onLayout={onLayout} style={{ width: '100%' }}>
+        <BlockCard
+          testID={testID}
+          title={config.title}
+          subtitle={config.description}
+          meta={busy ? <Spinner label="Searching" /> : undefined}
+          hint={selected ? undefined : <Text accessibilityLiveRegion="polite" color="textSecondary" numeric style={{ fontSize: 12 }}>{counter}</Text>}
+          actions={selected ? undefined : (
+            <>
+              <Button variant="secondary" size="small" disabled={!canPrev} aria-label="Previous"
+                onPress={() => machine.setPage(Math.max(0, pageOffset - config.pageSize))}>Previous</Button>
+              <Button variant="secondary" size="small" disabled={!canNext} aria-label="Next"
+                onPress={() => machine.setPage(pageOffset + config.pageSize)}>Next</Button>
+            </>
+          )}>
+          {selected ? (
+            <Detail record={selected} config={config} columns={columns} onBack={() => setSelectedId(null)} />
+          ) : (
+            <>
+              {config.searchColumns.length ? (
+                <Input
+                  value={text} onChangeText={onText}
+                  placeholder={`Search ${config.searchColumns.map(k => columns.get(k)?.label ?? k).join(', ')}`}
+                  aria-label="Search"
+                />
+              ) : null}
+
+              {facets.map(c => (
+                <Box key={c.key} role="group" aria-label={c.label} style={{ gap: 6 }}>
+                  <Text color="textPrimary" style={{ fontSize: 12, lineHeight: 16, fontWeight: '600' }}>{c.label}</Text>
+                  <Box row wrap style={{ gap: 6 }}>
+                    {(c.distinctValues ?? []).slice(0, 12).map(v => (
+                      <FacetChip
+                        key={v} label={v}
+                        /* Pressed means "showing only this". A rule that EXCLUDES the value compiles to the
+                           same column and value with `not`, and is the opposite fact — never drawn as on. */
+                        on={state.query.filters.some(f => f.column === c.key && f.value === v && !f.not)}
+                        onPress={() => machine.setFilter(c.key, v, c.type === 'multi' ? 'includes' : 'eq')}
+                      />
+                    ))}
+                  </Box>
+                </Box>
+              ))}
+
+              {config.sortColumns.length ? (
+                <Box row wrap align="center" style={{ gap: 8 }}>
+                  <Text color="textPrimary" style={{ fontSize: 12, lineHeight: 16, fontWeight: '600' }}>Sort</Text>
+                  <Button
+                    variant="secondary" size="xsmall"
+                    aria-label={`Sort: ${state.query.sort ? `${columns.get(state.query.sort.column)?.label ?? state.query.sort.column} ${state.query.sort.dir}` : 'none'}. Press to change`}
+                    onPress={() => {
+                      const next = config.sortColumns[(sortIndex + 1) % config.sortColumns.length]!;
+                      const dir = state.query.sort?.column === next && state.query.sort.dir === 'asc' ? 'desc' : 'asc';
+                      machine.setSort({ column: next, dir });
+                    }}>
+                    {sortLabel}
+                  </Button>
+                </Box>
+              ) : null}
+
+              {state.status === 'error' ? (
+                <Box role="group" aria-label="Error">
+                  <Callout alert title="Couldn’t read the records" action={<Button variant="secondary" size="xsmall" onPress={machine.retry} aria-label="Retry">Retry</Button>}>
+                    {state.data ? 'We could not refresh these records. Showing earlier results.' : 'We could not read these records.'}
+                  </Callout>
+                </Box>
+              ) : null}
+
+              <Box role="list">
+                {!state.data && state.status === 'error'
+                  ? null
+                  : !state.data
+                  ? Array.from({ length: 3 }, (_, i) => (
+                      <Box key={i} style={{ minHeight: 56, paddingVertical: 10, gap: 6, justifyContent: 'center' }}>
+                        <SkeletonBar width={`${70 - i * 12}%`} height={10} />
+                        <SkeletonBar width={`${50 - i * 8}%`} height={8} />
+                      </Box>
+                    ))
+                  : rows.length === 0
+                  ? <Box style={{ paddingVertical: 18 }}><Text color="textSecondary" style={{ fontSize: 13, lineHeight: 18 }}>{counter}</Text></Box>
+                  : rows.map((r, i) => (
+                      <Row
+                        key={r.id} record={r} index={i} seen={seen} config={config} columns={columns}
+                        selectable={config.selection === 'single'} last={i === rows.length - 1}
+                        onOpen={id => { setSelectedId(id); onSelect?.(id); }}
+                      />
+                    ))}
+              </Box>
+            </>
+          )}
+        </BlockCard>
+      </Box>
+    </SurfaceProvider>
+  );
+}
+
+export { chipRadius as DIRECTORY_CHIP_RADIUS };