duckfn-docs-kit 0.1.0

package/src/sql/sql.css

@@ -0,0 +1,397 @@
+/* Light-DOM styles for `<dfk-sql>`: the result container. It lives in the
+   element's light DOM (not the shadow root) because VTable injects a
+   *document-level* stylesheet that a shadow boundary could not host — the same
+   light-DOM exception as the TOC toggle (see AGENTS.md rule 9). It is created
+   only when a query runs, so the light DOM still starts empty (rule 11). Every
+   class carries the `dfk-sql-` prefix so nothing can collide with the host site.
+ *
+ * The code area — the editor and the buttons floating over it — is in the shadow
+ * root instead, and is styled by `DfkSql.css`.
+ *
+ * Imported through `kit.css`; the consuming site gets it with the one-line
+ * `@import 'duckfn-docs-kit/src/kit.css'` it already has. */
+
+/* The remark plugin prerenders two children: the loading ghost, and the original
+   code node (the class dates from when it was slotted as a read-only preview).
+   The code view is the CodeMirror editor now, so that copy must never show —
+   hiding it here rather than deleting it in JS also removes the flash between
+   parsing the prerendered HTML and the element upgrading.
+   The ghost is the one child that *does* show, and only while the element is
+   un-upgraded: once it upgrades it is unslotted like the rest and renders
+   nowhere, so no JS ever has to remove it. */
+dfk-sql > :not([slot]):not(.dfk-sql-editor-skeleton) {
+  display: none;
+}
+
+/* --- Loading placeholders ------------------------------------------------- */
+
+/* Two heavy libraries arrive through lazy `import()`s — CodeMirror for the
+   editor, VTable for a table result — and on a slow link both windows are long
+   enough to see. Each therefore gets a placeholder: one bar per line of SQL where
+   the editor goes, two rows where the table goes. Both are as tall as what
+   replaces them, so neither swap moves the page.
+
+   The editor ghost is drawn twice: here, for the window *before* the kit's JS has
+   defined `<dfk-sql>` at all (the bars are prerendered by `sql/remark.ts`), and
+   by `#setEditorPending` inside the shadow tree once it has. This file carries the
+   first copy and `DfkSql.css` the second — a shadow tree sees neither the
+   document's rules nor its `@keyframes` — so keep the bar and the timing of the
+   two in sync.
+
+   The line count is the SQL's *source* line count, which is a deliberate
+   approximation: a line long enough to wrap makes the editor taller than its
+   ghost, and knowing the wrapped height would mean laying the text out first —
+   measuring the site's fonts and column width — for a placeholder. */
+@keyframes dfk-sql-shimmer {
+  from {
+    background-position: 0% 0;
+  }
+  to {
+    background-position: 100% 0;
+  }
+}
+
+/* Before the element upgrades it has no shadow tree, and its prerendered text is
+   hidden by the rule above, so without this the block would be an invisible hole
+   that pops in and pushes the rest of the page down. `:not(:defined)` paints the
+   box the editor will live in; the bars inside come from the plugin. It also
+   keeps standing in when no JS ever runs, which is the honest thing to show for a
+   block that needs it. */
+dfk-sql:not(:defined) {
+  display: block;
+  margin: 1rem 0;
+  border: 1px solid var(--ifm-global-border-color, #e0e0e0);
+  border-radius: var(--ifm-global-radius, 0.4rem);
+  background: var(--ifm-background-surface-color, #fff);
+  /* The editor's own code font size, so a bar is as tall as a line of code. */
+  font-size: var(--ifm-code-font-size, 95%);
+  /* Floor of one line for a hand-written block, which carries no prerendered
+     ghost to be sized by. `border-box` (the sites' reset) counts the border. */
+  min-height: calc(1.6em + 10px);
+}
+
+/* The bars themselves: `sql/remark.ts` emits this markup for the pre-upgrade
+   window, `#setEditorPending` builds the same nodes inside the shadow tree, and
+   `DfkSql.css` carries that second copy of these two rules. */
+.dfk-sql-editor-skeleton {
+  /* CodeMirror's own content inset — `.cm-content` carries `padding: 4px 0` and
+     this box has none — on the container, so it is paid once, not per line. */
+  padding: 4px 0.75rem;
+}
+
+.dfk-sql-editor-skeleton-line {
+  display: flex;
+  align-items: center;
+  /* One code line box, exactly: `.cm-scroller`'s `line-height: 1.6`. The half
+     leading that centres a line's text is the flex centring here — margins would
+     collapse between neighbouring lines and stack the bars closer than the code
+     they stand in for. */
+  height: 1.6em;
+}
+
+.dfk-sql-editor-skeleton-line::before {
+  content: '';
+  flex: 1;
+  height: 0.75em;
+  border-radius: 0.25em;
+  background-color: var(--ifm-color-emphasis-200, #e6e6e6);
+  /* Base colour plus a lighter band travelling through it; `background-size:
+     200%` is what gives `background-position` room to move (at 100% it cannot). */
+  background-image: linear-gradient(
+    90deg,
+    transparent 0%,
+    var(--ifm-color-emphasis-100, #f5f5f5) 50%,
+    transparent 100%
+  );
+  background-size: 200% 100%;
+  animation: dfk-sql-shimmer 1.6s linear infinite;
+}
+
+/* `.dfk-sql-table` holds these while VTable's bundle is in flight; `mountTable`
+   drops them as soon as the canvas is in place — or hands the box to the error
+   view if the import failed. The box already has its final height (the renderer
+   derives `--dfk-sql-table-height` from the row count), so the rows only have to
+   read as "a table is coming"; the row rhythm comes from the renderer's
+   `ROW_HEIGHT`. Every row is built the same way, so the columns line up. */
+.dfk-sql-table-skeleton {
+  display: flex;
+  flex-direction: column;
+  /* Clipped to the box: a one-row result is shorter than two skeleton rows. */
+  height: 100%;
+  overflow: hidden;
+}
+
+.dfk-sql-table-skeleton-row {
+  display: flex;
+  align-items: center;
+  gap: 1.5rem;
+  height: var(--dfk-sql-skeleton-row-height, 30px);
+  padding: 0 0.75rem;
+  border-bottom: 1px solid var(--ifm-color-emphasis-100, #f5f5f5);
+}
+
+.dfk-sql-table-skeleton-cell {
+  flex: 1;
+  height: 0.7em;
+  border-radius: 0.25em;
+  background-color: var(--ifm-color-emphasis-200, #e6e6e6);
+  background-image: linear-gradient(
+    90deg,
+    transparent 0%,
+    var(--ifm-color-emphasis-100, #f5f5f5) 50%,
+    transparent 100%
+  );
+  background-size: 200% 100%;
+  animation: dfk-sql-shimmer 1.6s linear infinite;
+}
+
+/* A bar that sweeps forever is decoration; readers who asked for less motion get
+   the static grey. Mirrored in `DfkSql.css`. */
+@media (prefers-reduced-motion: reduce) {
+  .dfk-sql-editor-skeleton-line,
+  .dfk-sql-table-skeleton-cell {
+    animation: none;
+  }
+}
+
+.dfk-sql-result {
+  border: 1px solid var(--ifm-global-border-color, #e0e0e0);
+  border-top: none;
+  border-radius: 0 0 var(--ifm-global-radius, 0.4rem)
+    var(--ifm-global-radius, 0.4rem);
+  overflow: hidden;
+  background: var(--ifm-background-surface-color, #fff);
+}
+
+.dfk-sql-result:empty {
+  display: none;
+}
+
+.dfk-sql-text {
+  margin: 0;
+  padding: 0.5rem 0.75rem;
+  font-family: var(--ifm-font-family-monospace, ui-monospace, SFMono-Regular,
+    Menlo, monospace);
+  font-size: var(--ifm-code-font-size, 95%);
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.dfk-sql-error {
+  margin: 0;
+  padding: 0.5rem 0.75rem;
+  font-family: var(--ifm-font-family-monospace, ui-monospace, SFMono-Regular,
+    Menlo, monospace);
+  font-size: var(--ifm-code-font-size, 95%);
+  white-space: pre-wrap;
+  word-break: break-word;
+  color: var(--ifm-color-danger-contrast, #fff);
+  background: var(--ifm-color-danger, #d32f2f);
+}
+
+/* --- Result tabs --------------------------------------------------------- */
+
+/* The strip is a row holding the scrolling tab list and the corner button
+   (the fullscreen toggle, owned by `<dfk-sql>`). */
+.dfk-sql-tabs {
+  display: flex;
+  align-items: center;
+  padding-right: 0.3rem;
+  border-bottom: 1px solid var(--ifm-global-border-color, #e0e0e0);
+  background: var(--ifm-color-emphasis-100, #f5f5f5);
+}
+
+.dfk-sql-tab-list {
+  display: flex;
+  flex: 1;
+  gap: 0.25rem;
+  min-width: 0;
+  padding: 0.3rem 0.5rem 0;
+  overflow-x: auto;
+}
+
+.dfk-sql-tab {
+  padding: 0.15rem 0.65rem;
+  border: 1px solid transparent;
+  border-bottom: none;
+  border-radius: var(--ifm-global-radius, 0.4rem)
+    var(--ifm-global-radius, 0.4rem) 0 0;
+  background: transparent;
+  color: var(--ifm-color-emphasis-700, #666);
+  font-family: inherit;
+  font-size: 0.8rem;
+  line-height: 1.5;
+  white-space: nowrap;
+  cursor: pointer;
+}
+
+.dfk-sql-tab:hover {
+  color: var(--ifm-color-primary, #14459b);
+}
+
+.dfk-sql-tab-active {
+  border-color: var(--ifm-global-border-color, #e0e0e0);
+  background: var(--ifm-background-surface-color, #fff);
+  color: var(--ifm-font-color-base, #181818);
+}
+
+/* --- Icon buttons and their tooltips ------------------------------------- */
+
+/* The same rules (and the `[data-tip]` tooltip below) are declared in
+   `DfkSql.css`, because the buttons are split across the shadow boundary: the
+   code-block actions live in the shadow tree, the fullscreen toggle lives in
+   this light-DOM tab strip. Keep the two copies in sync. */
+.dfk-sql-icon-button {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.6rem;
+  height: 1.6rem;
+  padding: 0;
+  border: none;
+  border-radius: var(--ifm-global-radius, 0.25rem);
+  background: transparent;
+  color: var(--ifm-color-emphasis-700, #666);
+  cursor: pointer;
+  transition: background 0.12s ease, color 0.12s ease;
+}
+
+.dfk-sql-icon-button:hover:not(:disabled),
+.dfk-sql-icon-button:focus-visible {
+  background: var(--ifm-color-emphasis-200, #e6e6e6);
+  color: var(--ifm-color-primary, #14459b);
+}
+
+.dfk-sql-icon-button:disabled {
+  opacity: 0.45;
+  cursor: progress;
+}
+
+.dfk-sql-icon-button[hidden] {
+  display: none;
+}
+
+/* A sticky state, e.g. the wrap toggle while wrapping is on. */
+.dfk-sql-icon-on {
+  color: var(--ifm-color-primary, #14459b);
+}
+
+.dfk-sql-icon {
+  font-size: 1rem;
+}
+
+[data-tip]::after {
+  content: attr(data-tip);
+  position: absolute;
+  top: calc(100% + 0.3rem);
+  right: 0;
+  z-index: 2;
+  padding: 0.15rem 0.4rem;
+  border-radius: var(--ifm-global-radius, 0.25rem);
+  background: var(--ifm-color-emphasis-800, #333);
+  color: var(--ifm-color-emphasis-0, #fff);
+  font-size: 0.7rem;
+  line-height: 1.4;
+  white-space: nowrap;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.12s ease;
+}
+
+[data-tip]:hover::after,
+[data-tip]:focus-visible::after {
+  opacity: 1;
+}
+
+/* --- Panels -------------------------------------------------------------- */
+
+.dfk-sql-panels {
+  display: flex;
+  flex-direction: column;
+}
+
+/* `overscroll-behavior: contain` is what stops a wheel that has reached the
+   bottom of the table from continuing into the page scroll (the page lurches
+   upward and the example leaves the screen). It is not inherited, so it is
+   declared on every scrolling box, including VTable's inner scroll containers
+   under `.dfk-sql-table`. */
+.dfk-sql-panel,
+.dfk-sql-table,
+.dfk-sql-table *,
+.dfk-sql-svg {
+  overscroll-behavior: contain;
+}
+
+.dfk-sql-panel {
+  min-height: 0;
+  overflow: auto;
+}
+
+/* --- Rendered results ---------------------------------------------------- */
+
+.dfk-sql-table {
+  width: 100%;
+  /* VTable measures its container, so the box needs a real height; a taller
+     result grows with the rows up to a ceiling. */
+  height: var(--dfk-sql-table-height, 240px);
+}
+
+.dfk-sql-frame {
+  display: block;
+  width: var(--dfk-sql-preview-width, 100%);
+  height: var(--dfk-sql-preview-height, 360px);
+  border: none;
+  background: #fff;
+}
+
+.dfk-sql-svg {
+  width: var(--dfk-sql-preview-width, 100%);
+  height: var(--dfk-sql-preview-height, auto);
+  padding: 0.5rem;
+  overflow: auto;
+}
+
+.dfk-sql-svg > svg {
+  max-width: 100%;
+  height: auto;
+}
+
+/* --- Fullscreen ---------------------------------------------------------- */
+
+/* Also carries `.dfk-sql-result`, so `overflow` and the radius are re-declared
+   here rather than fought with `!important`.
+   The background must be the *surface* colour, not `--ifm-background-color`:
+   a site may legitimately define the latter as `transparent` (this one does),
+   which would leave the overlay see-through with the page showing underneath. */
+.dfk-sql-result-expanded {
+  position: fixed;
+  inset: 0;
+  z-index: 2147483000;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  border: none;
+  border-radius: 0;
+  background: var(--ifm-background-surface-color, #fff);
+}
+
+.dfk-sql-result-expanded .dfk-sql-panels,
+.dfk-sql-result-expanded .dfk-sql-panel {
+  flex: 1;
+}
+
+.dfk-sql-result-expanded .dfk-sql-table {
+  /* The extra height is the point of the fullscreen view. */
+  height: 100%;
+}
+
+.dfk-sql-result-expanded .dfk-sql-frame {
+  height: 100%;
+}
+
+/* An inline `<svg>` gets the same treatment as the frame and the table so the
+   panel is one full-height scroll area rather than a strip. */
+.dfk-sql-result-expanded .dfk-sql-svg {
+  height: 100%;
+}

package/src/sql/styles.ts

@@ -0,0 +1,24 @@
+// The `<dfk-sql>` code box's shadow-root CSS as an inline string (Vite `?inline`
+// import), mirroring `home/styles.ts`. It covers the CodeMirror editor and the
+// action cluster, both of which live in this tree. Only the *result* container
+// stays in the light DOM, styled by `sql.css` through `kit.css` instead: VTable
+// injects a document-level stylesheet, which a shadow boundary could not host.
+//
+// The type declaration lives in `vite-env.d.ts`; `tsc` never resolves the
+// `?inline` suffix, so the module graph stays buildable without Vite running.
+import sqlCss from './DfkSql.css?inline';
+
+let sheet: CSSStyleSheet | null = null;
+
+/**
+ * The one parsed stylesheet shared by every `<dfk-sql>` shadow root.
+ * Created lazily: `CSSStyleSheet` does not exist during Docusaurus' Node
+ * prerender, and only the browser ever calls this.
+ */
+export function sqlStyles(): CSSStyleSheet {
+  if (!sheet) {
+    sheet = new CSSStyleSheet();
+    sheet.replaceSync(sqlCss);
+  }
+  return sheet;
+}

package/src/theme/tokens.css

@@ -0,0 +1,75 @@
+/**
+ * Brand colour tokens for duckfn-family docs sites.
+ *
+ * The palette comes from the project logo (drawn with a deep blue body,
+ * #14459b, and a golden beak, #fcb103). The `--duckfn-*` variables are what the
+ * shared components (home.css) pick their tints, glows and borders from, so the
+ * brand colour stays defined in exactly one place. They are written out
+ * explicitly instead of derived with `color-mix()` to avoid relying on a newer
+ * CSS feature for something this central.
+ *
+ * Contrast, checked against the palettes below:
+ *   #14459b on white           8.9:1   -> light-mode primary for text and links
+ *   white on #14459b           8.9:1   -> buttons and badges
+ *   #4d8fe8 on #1b1b1d         5.2:1   -> dark-mode primary for text and links
+ *   #fcb103 on #14459b         4.8:1   -> yellow is only legible on brand blue
+ *   #fcb103 on white           1.8:1   -> NOT a text colour; see the note below.
+ *
+ * The `--ifm-*` Infima wiring (the seven-step primary ramp) deliberately does
+ * NOT live here: each site owns that mapping for its own brand.
+ */
+:root {
+  --duckfn-blue: #14459b;
+  /* Ends of the gradient the homepage headline is painted with. */
+  --duckfn-blue-deep: #0e306c;
+  --duckfn-blue-bright: #1a5aca;
+  /* Tinted surfaces: card icon chips, the code showcase band, hover shadows. */
+  --duckfn-blue-soft: #e8eefb;
+  --duckfn-tint: #f6f8fc;
+  /* Kept faint on purpose: the home page stretches these over a very large
+     radius, and a stronger tint shows the gradient's steps as visible bands. */
+  --duckfn-glow: rgba(20, 69, 155, 0.12);
+  --duckfn-glow-warm: rgba(252, 177, 3, 0.16);
+  --duckfn-card-bg: #ffffff;
+  --duckfn-card-border: #e3e8f2;
+  --duckfn-shadow: 0 8px 24px rgba(20, 69, 155, 0.12);
+  --duckfn-yellow: #fcb103;
+  /* Home page buttons, kept apart from the primary because the dark mode value
+     of `--ifm-color-primary` is too light to carry white text. Measured against
+     their own label: white on #14459b is 8.9:1, white on the hover #0e306c is
+     12.7:1. The outline border is decorative — the label above it carries the
+     contrast — so it is allowed to stay faint. */
+  --duckfn-btn-bg: #14459b;
+  --duckfn-btn-bg-hover: #0e306c;
+  --duckfn-btn-fg: #ffffff;
+  --duckfn-outline-border: #bccbe8;
+}
+
+/* For readability concerns, you should choose a lighter palette in dark mode.
+   The primary has to move well away from #14459b here: the deep blue only
+   reaches about 2.4:1 against #1b1b1d, which is unreadable for text. */
+[data-theme='dark'] {
+  --duckfn-blue: #4d8fe8;
+  --duckfn-blue-deep: #4d8fe8;
+  --duckfn-blue-bright: #9ecbff;
+  --duckfn-blue-soft: #17253d;
+  --duckfn-tint: #1f2733;
+  --duckfn-glow: rgba(77, 143, 232, 0.16);
+  --duckfn-glow-warm: rgba(252, 177, 3, 0.12);
+  --duckfn-card-bg: #242526;
+  --duckfn-card-border: #33405c;
+  --duckfn-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
+  --duckfn-yellow: #fcb103;
+  /* The dark primary is a light blue, so white on it would only reach 3.3:1.
+     The button therefore gets its own deeper blue: white on #2f6fd0 is 4.9:1,
+     and the one-notch-lighter hover stays at 4.4:1. */
+  --duckfn-btn-bg: #2f6fd0;
+  --duckfn-btn-bg-hover: #3576dd;
+  --duckfn-btn-fg: #ffffff;
+  --duckfn-outline-border: #33405c;
+}
+
+/* The yellow is an accent, never a text colour: #fcb103 on white is 1.8:1.
+   Safe uses (all already at or above 4.5:1): as a chip behind the deep blue,
+   as the icon chip background in dark mode, as a decorative underline or
+   border, and for small shapes that are not the only carrier of meaning. */

package/src/toc-toggle/TocToggle.css

@@ -0,0 +1,69 @@
+/**
+ * Table-of-contents toggle styles.
+ *
+ * Docusaurus has no `hideable` option for the right-hand TOC, so the control
+ * and the layout switch are provided by the kit's `toc-toggle` module: the
+ * button is injected above the TOC, and the `toc-collapsed` class on `<body>`
+ * drives the rules below.
+ */
+
+.toc-toggle {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  /* Right edge of the TOC column, next to the list it controls. */
+  margin-left: auto;
+  margin-bottom: 0.5rem;
+  border-radius: 50%;
+  background-color: var(--ifm-color-emphasis-200);
+  color: var(--ifm-color-emphasis-800);
+  transition: background-color var(--ifm-transition-fast)
+    var(--ifm-transition-timing-default);
+}
+
+.toc-toggle:hover {
+  background-color: var(--ifm-color-emphasis-300);
+}
+
+.toc-toggle::after {
+  content: '';
+  width: 1rem;
+  height: 1rem;
+  background-color: currentColor;
+  /* chevron-right: "push the TOC away"; it is flipped when collapsed. */
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='%23000' d='M10 6L8.59 7.41 13.17 12l-4.58 4.59L10 18l6-6z'/%3E%3C/svg%3E")
+    center / contain no-repeat;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='%23000' d='M10 6L8.59 7.41 13.17 12l-4.58 4.59L10 18l6-6z'/%3E%3C/svg%3E")
+    center / contain no-repeat;
+  transition: transform var(--ifm-transition-fast)
+    var(--ifm-transition-timing-default);
+}
+
+body.toc-collapsed .toc-toggle::after {
+  transform: rotate(180deg);
+}
+
+/* Collapsed: the column shrinks to a strip that keeps the button reachable, the
+   list is hidden, and the article takes the freed width. Infima sizes columns
+   through --ifm-col-width, so overriding that one property covers the width.
+
+   These rules go into the theme's own cascade layer on purpose: `future.v4`
+   makes Docusaurus emit layered CSS, and for `!important` declarations layer
+   order wins over specificity — an unlayered `!important` loses to a layered
+   one, so the `max-width` below would silently do nothing outside this layer. */
+@layer docusaurus.theme-classic {
+  body.toc-collapsed .toc-column {
+    --ifm-col-width: 2.5rem;
+    padding: 0;
+  }
+
+  body.toc-collapsed .toc-column .theme-doc-toc-desktop {
+    display: none;
+  }
+
+  body.toc-collapsed [class*='docItemCol'] {
+    max-width: 100% !important;
+  }
+}