@signalcore/ui 0.1.0 → 1.0.0-beta.1

package/src/AgentCard.tsx

@@ -0,0 +1,123 @@
+import type { ReactNode } from "react";
+
+import { agentGlyph } from "./agentIcons";
+import { classes } from "./classes";
+import { agentTint } from "./tint";
+
+/**
+ * One thing the card says: what the host knows it by (`renderValue` switches on it), its label,
+ * its text, the words that stand in while it is empty, and whether it is a long text.
+ */
+export interface CardField<Key extends string = string> {
+  key: Key;
+  label: string;
+  value: string;
+  /** Drawn, muted, while the value is empty. */
+  placeholder?: string | undefined;
+  /** A long text: its own section under a small heading, at a reading measure. */
+  block?: boolean | undefined;
+}
+
+/** The parts, by the class each carries; `classNames` adds a host's own under the same keys. */
+export type CardPart =
+  | "sc-card"
+  | "sc-card--sky"
+  | "sc-card--rose"
+  | "sc-card--sand"
+  | "sc-card__head"
+  | "sc-card__mark"
+  | "sc-card__who"
+  | "sc-card__name"
+  | "sc-card__role"
+  | "sc-card__facts"
+  | "sc-card__fact"
+  | "sc-card__body"
+  | "sc-card__row"
+  | "sc-card__label"
+  | "sc-card__value"
+  | "sc-card__empty";
+
+type ClassNames = Partial<Record<CardPart, string>> | undefined;
+
+export interface AgentCardProps<Key extends string = string> {
+  /** The agent's id: its mark keeps the tint `agentTint` gives it wherever it appears. */
+  id: string;
+  /** Its mark (`AGENT_ICONS`), in its tint; a sparkle until it has one. */
+  icon?: string | null | undefined;
+  /** Who it is, at the top: the name over the role. */
+  name: CardField<Key>;
+  role: CardField<Key>;
+  /**
+   * What it says, in order: the short ones (its model, when it was made) as a list of
+   * properties, each label beside its value; the long ones (`block`: its description, its
+   * instructions) under them, each its own section.
+   */
+  fields: readonly CardField<Key>[];
+  /**
+   * Draws a value in the text's place, the name and role included: the host's own control, so
+   * the card edits where it stands. `undefined` leaves that field to the card.
+   */
+  renderValue?: ((field: CardField<Key>) => ReactNode) | undefined;
+  classNames?: ClassNames;
+}
+
+/**
+ * The Ficha, as a page about the agent: its mark bare in its tint beside its name, the role
+ * under it; its short facts as a quiet list of properties, the label beside its value; then its
+ * long texts, each under a small heading at a reading measure. Typography and space carry it; no
+ * band, no tiles. The card draws text; a host that edits in place gives `renderValue`.
+ */
+export function AgentCard<Key extends string = string>({
+  id,
+  icon,
+  name,
+  role,
+  fields,
+  renderValue,
+  classNames,
+}: AgentCardProps<Key>) {
+  const Glyph = agentGlyph(icon);
+  const draw = (field: CardField<Key>): ReactNode => {
+    const own = renderValue?.(field);
+    if (own !== undefined) return own;
+    if (field.value.trim() !== "") return field.value;
+    return (
+      <span className={classes(classNames, "sc-card__empty")}>{field.placeholder ?? "—"}</span>
+    );
+  };
+  const facts = fields.filter((field) => !field.block);
+  const texts = fields.filter((field) => field.block);
+  return (
+    <article className={`sc ${classes(classNames, "sc-card", `sc-card--${agentTint(id)}`)}`}>
+      <header className={classes(classNames, "sc-card__head")}>
+        <span aria-hidden className={classes(classNames, "sc-card__mark")}>
+          <Glyph weight="duotone" />
+        </span>
+        <div className={classes(classNames, "sc-card__who")}>
+          <h2 className={classes(classNames, "sc-card__name")}>{draw(name)}</h2>
+          <p className={classes(classNames, "sc-card__role")}>{draw(role)}</p>
+        </div>
+      </header>
+      {facts.length > 0 && (
+        <dl className={classes(classNames, "sc-card__facts")}>
+          {facts.map((field) => (
+            <div key={field.key} className={classes(classNames, "sc-card__fact")}>
+              <dt className={classes(classNames, "sc-card__label")}>{field.label}</dt>
+              <dd className={classes(classNames, "sc-card__value")}>{draw(field)}</dd>
+            </div>
+          ))}
+        </dl>
+      )}
+      {texts.length > 0 && (
+        <dl className={classes(classNames, "sc-card__body")}>
+          {texts.map((field) => (
+            <div key={field.key} className={classes(classNames, "sc-card__row")}>
+              <dt className={classes(classNames, "sc-card__label")}>{field.label}</dt>
+              <dd className={classes(classNames, "sc-card__value")}>{draw(field)}</dd>
+            </div>
+          ))}
+        </dl>
+      )}
+    </article>
+  );
+}