@flamingo-stack/openframe-frontend-core 0.0.847 → 0.0.848

package/src/types/design-doc.ts

@@ -3,9 +3,11 @@
 //
 // Participant sections are keyed by the employee DEPARTMENT (FK to the ONE
 // `departments` table — see department.ts); there is no function enum.
-// A doc has no status: it is READY when every section is signed off and no
-// blocking comment is open. That math lives in the hub's
+// A doc's READINESS is derived: it is ready when every section is signed off and
+// no blocking comment is open. That math lives in the hub's
 // `lib/utils/design-doc-gate.ts` (isomorphic, shared by server + client).
+// Beside it a PERSON may set a lifecycle status (`lifecycle_status`: postponed,
+// shipped, archived), which replaces readiness on every surface while it is set.
 
 // MIGRATION NOTE (2026-09-11). This file dropped `status`, `DesignDocStatus`,
 // `DesignDocStatusTransition`, `approved_at`, `dri_vacated_by`, `by_status` and
@@ -53,7 +55,15 @@ import type { EntityAuthor } from './entity-author';
 /** One value of `design_doc_vocabulary.kind` — the STRUCTURAL list (one per
  *  value column), the only design-doc vocabulary that is code. */
 export type DesignDocVocabularyKind =
-  'tier' | 'spec_mode' | 'participant_status' | 'comment_type' | 'comment_status' | 'link_type' | 'media_type';
+  | 'tier'
+  | 'spec_mode'
+  | 'participant_status'
+  | 'comment_type'
+  | 'comment_status'
+  | 'link_type'
+  | 'media_type'
+  | 'lifecycle_status'
+  | 'readiness';
 
 /** A `design_doc_vocabulary` row, as the DAL and the vocabulary API return it. */
 export interface DesignDocVocabularyOption {
@@ -107,6 +117,24 @@ export type DesignDocCommentStatus = string;
 export type DesignDocLinkType = string;
 /** A `design_doc_vocabulary.value` of kind `media_type`. */
 export type DesignDocMediaType = string;
+/**
+ * A `design_doc_vocabulary.value` of kind `lifecycle_status`: a status a PERSON sets (postponed, shipped, archived),
+ * beside the readiness the sign-offs decide. Null on a doc = active, and its readiness shows.
+ */
+export type DesignDocLifecycleStatus = string;
+/**
+ * A `design_doc_vocabulary.value` of kind `readiness`: the stage the sign-offs put a doc in (not ready, in active
+ * work, blocked, ready to build). The hub picks the row by its role; the words and the colour are the row's.
+ */
+export type DesignDocReadiness = string;
+
+/** A vocabulary value as a card shows it, resolved by the hub so a surface without the vocabulary can draw it. */
+export interface DesignDocVocabularyDisplay {
+  value: string;
+  label: string;
+  /** A `StatusBadge` colorScheme name. */
+  color_scheme: string;
+}
 
 // ---------------------------------------------------------------------------
 // Rows (as returned by the hub DAL — hydrated)
@@ -258,6 +286,15 @@ export interface DesignDoc {
   comments: DesignDocComment[];
   completion: DesignDocCompletion;
   my_open_work?: DesignDocMyOpenWork;
+  /** The status a person set (postponed, shipped, archived); null = active, its readiness shows. */
+  lifecycle_status: DesignDocLifecycleStatus | null;
+  /** That status as the vocabulary words it, resolved by the hub (null when none is set). */
+  lifecycle?: DesignDocVocabularyDisplay | null;
+  /** When the status was last set or cleared, and by whom. */
+  lifecycle_status_changed_at: string | null;
+  lifecycle_status_changed_by?: DesignDocPerson | null;
+  /** The stage its sign-offs put it in, as the vocabulary words it, resolved by the hub. */
+  readiness?: DesignDocVocabularyDisplay | null;
 }
 
 // ---------------------------------------------------------------------------
@@ -328,6 +365,8 @@ export interface UpdateDesignDocData {
    */
   feature_lead_ids?: string[];
   links?: DesignDocLinkInput[];
+  /** A `lifecycle_status` value, or null to make the doc active again. Anyone who may edit the doc may set it. */
+  lifecycle_status?: DesignDocLifecycleStatus | null;
   /** OCC token — the `updated_at` the editor seeded from; mismatch → 409. */
   expected_updated_at?: string;
 }
@@ -358,10 +397,18 @@ export interface AddDesignDocCommentData {
   body: string;
 }
 
-/** The dashboard's readiness filter (`?ready=`). */
-export type DesignDocReadyFilter = 'ready' | 'not_ready';
+/** The dashboard's readiness filter (`?ready=`): one `readiness` value. */
+export type DesignDocReadyFilter = DesignDocReadiness;
+
+/**
+ * The dashboard's status filter (`?status=`): `active` (no lifecycle status set, the default) or one
+ * `lifecycle_status` value.
+ */
+export type DesignDocLifecycleFilter = 'active' | DesignDocLifecycleStatus;
 
 export interface DesignDocFilters {
+  /** Defaults to `active`: a doc a person postponed, shipped or archived is listed only under its own status. */
+  lifecycle?: DesignDocLifecycleFilter;
   ready?: DesignDocReadyFilter;
   /** One or more `spec_mode` values (CSV on the wire). */
   spec_mode?: string;
@@ -378,16 +425,18 @@ export interface DesignDocListResponse {
    *  filter itself — so a filtered row still shows what the other value holds. */
   facets: {
     spec_mode: Record<string, number>;
-    /** The same over readiness (`ready` / `not_ready`), MINUS the ready filter itself: the filter row's options. */
-    ready: Record<'ready' | 'not_ready', number>;
+    /** The same over readiness (each `readiness` value), MINUS the ready filter itself: the filter row's options. */
+    ready: Record<DesignDocReadiness, number>;
+    /** The same over the status filter (`active` and each `lifecycle_status` value), MINUS the status filter itself. */
+    lifecycle: Record<string, number>;
   };
 }
 
+/** Counted over ACTIVE docs (no lifecycle status), so postponed, shipped and archived docs never inflate open work. */
 export interface DesignDocStats {
   total: number;
-  /** Docs whose every section is signed off with no open blocking comment. */
-  ready: number;
-  not_ready: number;
+  /** How many active docs each `readiness` value holds, zeros included. */
+  readiness: Record<DesignDocReadiness, number>;
   waiting_on_me_docs: number;
   waiting_on_me_tasks: number;
 }

package/src/utils/design-doc-readiness.ts

@@ -1,34 +1,33 @@
 /**
- * A design doc's readiness in words — THE wording every surface prints (the hub's design-docs screens, its doc
- * page, the lib's design-doc card): "Ready to build" once every department section is signed off and no blocking
- * comment is open, else "Not ready", and the sign-off caption beside it. Pure, zero-import beyond the type.
+ * A design doc's status as every surface draws it (the hub's design-docs screens, its doc page, the lib's design-doc
+ * cards), and its sign-off caption.
+ *
+ * Both halves of the status are vocabulary rows the hub resolves onto the doc, so no surface holds a word or a colour:
+ *   - its READINESS (`doc.readiness`): the stage the sign-offs put it in (not ready, in active work, blocked, ready to
+ *     build), picked by the hub from the `readiness` rows by role;
+ *   - a LIFECYCLE status a person set (`doc.lifecycle`: postponed, shipped, archived). While one is set it is what the
+ *     doc shows; cleared, the readiness shows again.
+ *
+ * The sign-off caption is counts only ("4/6 signed off · 1 blocking"): the status has its own badge.
+ * Pure, zero-import beyond the type.
  */
-import type { DesignDocCompletion } from '../types/design-doc';
+import type { DesignDoc, DesignDocCompletion, DesignDocVocabularyDisplay } from '../types/design-doc';
 
-export const DESIGN_DOC_READINESS = ['ready', 'not_ready'] as const;
-export type DesignDocReadiness = (typeof DESIGN_DOC_READINESS)[number];
-
-/** Each readiness's label and badge colour (a `StatusBadge` scheme). */
-export const DESIGN_DOC_READINESS_DISPLAY: Record<
-  DesignDocReadiness,
-  { label: string; scheme: 'success' | 'default' }
-> = {
-  ready: { label: 'Ready to build', scheme: 'success' },
-  not_ready: { label: 'Not ready', scheme: 'default' },
-};
-
-/** Ready to build ⇔ `completion.isComplete` (every section signed off, no open blocking comment). */
-export const designDocReadiness = (completion: Pick<DesignDocCompletion, 'isComplete'>): DesignDocReadiness =>
-  completion.isComplete ? 'ready' : 'not_ready';
+/** What the doc's status badge says: its lifecycle status when a person set one, else its readiness (null from a hub
+ *  that resolves neither). */
+export function designDocStatusDisplay(
+  doc: Pick<DesignDoc, 'lifecycle' | 'readiness'>,
+): DesignDocVocabularyDisplay | null {
+  return doc.lifecycle ?? doc.readiness ?? null;
+}
 
-/** "4/6 reviews signed off" */
+/** "4/6 signed off" */
 export function formatCompletionLabel(completion: Pick<DesignDocCompletion, 'total' | 'completed'>): string {
-  return `${completion.completed}/${completion.total} reviews signed off`;
+  return `${completion.completed}/${completion.total} signed off`;
 }
 
-/** The SAME label plus readiness and the blocking veto (the dashboard row, the doc page, the card). */
+/** The SAME count plus the blocking veto ("4/6 signed off · 1 blocking"): the dashboard row, the doc page, the card. */
 export function formatCompletionLabelWithBlockers(completion: DesignDocCompletion): string {
   const base = formatCompletionLabel(completion);
-  if (completion.isComplete) return `${DESIGN_DOC_READINESS_DISPLAY.ready.label} · ${base}`;
   return completion.openBlocking > 0 ? `${base} · ${completion.openBlocking} blocking` : base;
 }