explico 0.7.0 → 0.11.0

package/src/components/examples/CompactExamples.astro

@@ -1,82 +1,121 @@
 ---
+/**
+ * A set of worked examples, one tab each (`CompactExample.astro`) — a
+ * numbered kind of its own, like a knowledge check
+ * (docs/plans/titles-and-containers.md Part 6, Q11): `Example 1.1.1`,
+ * anchored `#ex-‹id›`, cited with `[[ex-‹id›]]`. The author names only the
+ * topic, in `short` (rule S1 measures it); the engine's heading
+ * (`BlockHeading.astro`) puts the "Example" badge and the number before it.
+ * `remark-notation.mjs` numbers the set and hands this component its
+ * `number` and `anchorId`; an unplaced set renders without a number.
+ *
+ * **The set is a section of its own**, the way a `<Memo>` is (Part 4): its
+ * heading sits in a collapsible `.sl-heading-wrapper` marked
+ * `data-section-to-end`, so `CollapsibleSections.astro` folds the whole set —
+ * the gutter chevron, the hover peek, "Hidden here: 2 worked examples",
+ * persistence (`section:ex-‹id›`) and print-as-shown — and the chain icon
+ * copies its link. Its first-visit state is the course's
+ * `disclosure.workedExamples`; `defaultOpen` overrides it at one set. The
+ * frame is an accent card (`ex-tier-accent`, `surfaces.css`). Unlike a memo's
+ * `######`, the heading is an `<h2>` of the outline, as a knowledge check's
+ * is: it ends the section before it, "On this page" lists it, and rules S6
+ * and S7 read it as a `##` (`gate-heading-structure.ts`).
+ */
+import BlockHeading from '../BlockHeading.astro';
+import { courseDisclosure } from '../disclosure/course-disclosure';
+
 interface Props {
-  /** Text shown on the native disclosure while the examples are collapsed. */
-  summary?: string;
-  /** Optional one-line cue below the disclosure title. */
+  /** Stable lowercase/hyphenated key: the set's anchor `#ex-‹id›` and `[[ex-‹id›]]`. */
+  id: string;
+  /** The set's topical title, after the engine's "Example" badge and number. */
+  short: string;
+  /** Optional one-line cue above the tabs. */
   hint?: string;
-  /** Accessible name for the tab list created by progressive enhancement. */
+  /** Accessible name for the tab list created by progressive enhancement. Default: `short`. */
   tabsLabel?: string;
+  /** State for a reader with nothing saved yet. Default: the course's `disclosure.workedExamples`. */
+  defaultOpen?: boolean;
+  /** Persist the reader's open/closed choice across visits, per page. Default: `true`. */
+  rememberState?: boolean;
+  /** Computed by `remark-notation.mjs` — never author this directly. */
+  number?: string;
+  /** Computed by `remark-notation.mjs` — never author this directly. */
+  anchorId?: string;
+}
+
+if ('summary' in Astro.props) {
+  throw new Error(
+    '<CompactExamples> has no `summary` prop: the set is named by its `short` title.',
+  );
 }
 
 const {
-  summary = 'Worked examples',
-  hint = 'Open and choose an example.',
-  tabsLabel = summary,
+  id,
+  short,
+  hint,
+  tabsLabel,
+  defaultOpen,
+  rememberState = true,
+  number,
+  anchorId,
 } = Astro.props;
+
+if (typeof id !== 'string' || !id.trim()) {
+  throw new Error(
+    '<CompactExamples> requires an `id`: the set is anchored `#ex-‹id›` and cited with `[[ex-‹id›]]`.',
+  );
+}
+if (typeof short !== 'string' || !short.trim()) {
+  throw new Error(
+    `<CompactExamples id="${id}"> requires a \`short\` title naming its topic; the engine draws "Example" and the number before it.`,
+  );
+}
+
+const open = defaultOpen ?? (await courseDisclosure()).workedExamples.defaultOpen;
 ---
 
-<compact-examples data-tabs-label={tabsLabel}>
-  <details class="compact-examples">
-    <summary class="compact-examples__summary">
-      <span class="compact-examples__title">{summary}</span>
-      {hint && <span class="compact-examples__hint">{hint}</span>}
-    </summary>
-    <div class="compact-examples__body">
-      <slot />
-    </div>
-  </details>
+<compact-examples
+  class="compact-examples ex-section-card ex-tier-accent"
+  data-tabs-label={tabsLabel ?? short}
+>
+  <BlockHeading
+    kind="example"
+    anchorId={anchorId ?? `ex-${id}`}
+    title={short}
+    number={number}
+    collapsible={true}
+    defaultOpen={open}
+    rememberState={rememberState}
+    sectionToEnd
+    class="compact-examples__titlebar"
+  />
+  {hint && <div class="compact-examples__hint">{hint}</div>}
+  <div class="compact-examples__body">
+    <slot />
+  </div>
 </compact-examples>
 
 <style>
+  /* The accent card (`ex-tier-accent`) draws the surface, border, radius and
+     shadow; `ex-section-card` (`surfaces.css`) its padding, which is also the
+     gutter the section chevron centres in. */
   compact-examples {
     display: block;
-    margin-block: 1.5rem;
-  }
-
-  .compact-examples {
-    overflow: clip;
-    border: 1px solid var(--sl-color-gray-5);
-    border-radius: 0.75rem;
-    background: var(--sl-color-gray-7);
-  }
-
-  .compact-examples__summary {
-    padding: 0.8rem 1rem;
-    cursor: pointer;
-  }
-
-  .compact-examples__summary::marker {
-    color: var(--sl-color-text-accent);
-  }
-
-  .compact-examples__summary:focus-visible {
-    outline: 3px solid var(--sl-color-accent);
-    outline-offset: -3px;
-  }
-
-  .compact-examples__title {
-    font-weight: 700;
   }
 
   .compact-examples__hint {
-    display: block;
-    margin-block-start: 0.15rem;
     color: var(--sl-color-gray-3);
     font-size: var(--sl-text-sm);
   }
 
-  .compact-examples__body {
-    padding: 0.25rem 1rem 1rem;
-    border-block-start: 1px solid var(--sl-color-gray-5);
-  }
-
+  /* The tab row spans the card, edge to edge, under the title. */
   :global(.compact-examples__tabs) {
     display: flex;
     gap: 0.25rem;
     overflow-x: auto;
-    margin: 0 -1rem 1rem;
-    padding: 0.55rem 1rem 0;
-    border-block-end: 1px solid var(--sl-color-gray-5);
+    margin: 0.25rem calc(-1 * var(--ex-pad-box)) 1rem;
+    padding: 0 var(--ex-pad-box);
+    border-block-end: var(--ex-edge-border);
   }
 
   :global(.compact-examples__tab) {
@@ -108,23 +147,15 @@ const {
   }
 
   @media print {
-    .compact-examples {
-      overflow: visible;
-      border: 0;
-      background: transparent;
-    }
-
-    .compact-examples__summary,
+    /* Print follows the screen (`../disclosure/print-as-shown.ts`): an open
+       set prints every example in turn under its own title, no tabs; a
+       folded one prints its heading and a "(content collapsed …)" note, like
+       any section. */
+    .compact-examples__hint,
     :global(.compact-examples__tabs) {
       display: none;
     }
 
-    .compact-examples__body {
-      display: block !important;
-      padding: 0;
-      border: 0;
-    }
-
     :global(.compact-example[hidden]) {
       display: block !important;
     }
@@ -146,12 +177,10 @@ const {
     connectedCallback() {
       if (this.dataset.enhanced === 'true') return;
 
-      const details =
-        this.querySelector<HTMLDetailsElement>(':scope > details');
-      const body = details?.querySelector<HTMLElement>(
-        ':scope > .compact-examples__body',
-      );
-      if (!details || !body) return;
+      // Not `:scope >`: `CollapsibleSections` may already have moved the
+      // body into the set's `<details>` — the two scripts run in either order.
+      const body = this.querySelector<HTMLElement>('.compact-examples__body');
+      if (!body) return;
 
       const panels = Array.from(
         body.querySelectorAll<HTMLElement>(':scope > [data-compact-example]'),
@@ -224,28 +253,6 @@ const {
 
       body.prepend(tablist);
       activate(0);
-
-      let openBeforePrint: boolean | undefined;
-      const enterPrintMode = () => {
-        if (document.querySelector('[data-explico-print-controller]')) return;
-        if (openBeforePrint !== undefined) return;
-        openBeforePrint = details.open;
-        details.open = true;
-      };
-      const leavePrintMode = () => {
-        if (document.querySelector('[data-explico-print-controller]')) return;
-        if (openBeforePrint === undefined) return;
-        details.open = openBeforePrint;
-        openBeforePrint = undefined;
-      };
-      const printMedia = window.matchMedia('print');
-      printMedia.addEventListener('change', (event) => {
-        if (event.matches) enterPrintMode();
-        else leavePrintMode();
-      });
-      window.addEventListener('beforeprint', enterPrintMode);
-      window.addEventListener('afterprint', leavePrintMode);
-      if (printMedia.matches) enterPrintMode();
     }
   }