duckfn-docs-kit 0.1.0

package/src/remark.ts

@@ -0,0 +1,60 @@
+import type {Plugin} from 'unified';
+
+/**
+ * Replaces a build-time version placeholder in the docs tree.
+ *
+ * Written as a plain text substitution so it can live in a shared package: the
+ * version value is passed in by the consuming site (it is the one thing that is
+ * *not* shared), and only "pure text" carriers are touched —
+ * `text` / `inlineCode` / `code` nodes. MDX expression nodes (`{expr}`) and ESM
+ * nodes are deliberately left alone, so this never interferes with MDX's own
+ * evaluation.
+ *
+ * This is Node-side build code: it must not touch `window` / `document`.
+ */
+export const DEFAULT_VERSION_PLACEHOLDER = '{{DUCKFN_VERSION}}';
+
+export interface VersionPlaceholderOptions {
+  /** The real version string to substitute in, e.g. `0.0.13`. */
+  version: string;
+  /** Override the token if a site uses a different one. */
+  placeholder?: string;
+}
+
+const TEXT_NODE_TYPES = new Set(['text', 'inlineCode', 'code']);
+
+interface TextLikeNode {
+  type: string;
+  value?: unknown;
+  children?: TextLikeNode[];
+}
+
+export const remarkVersionPlaceholder: Plugin<[VersionPlaceholderOptions]> =
+  ({version, placeholder = DEFAULT_VERSION_PLACEHOLDER}) =>
+  (tree) => {
+    const walk = (node: unknown): void => {
+      if (typeof node !== 'object' || node === null) {
+        return;
+      }
+
+      const candidate = node as TextLikeNode;
+      const value = candidate.value;
+
+      if (
+        typeof candidate.type === 'string' &&
+        typeof value === 'string' &&
+        TEXT_NODE_TYPES.has(candidate.type) &&
+        value.includes(placeholder)
+      ) {
+        // Exact-token replacement only — no general `{{…}}` parsing — so other
+        // content is left untouched.
+        candidate.value = value.split(placeholder).join(version);
+      }
+
+      if (Array.isArray(candidate.children)) {
+        candidate.children.forEach(walk);
+      }
+    };
+
+    walk(tree);
+  };

package/src/sql/DfkSql.css

@@ -0,0 +1,226 @@
+/* Shadow-root styles for `<dfk-sql>`: the code box — the CodeMirror editor and
+   the action cluster floating in its top-right corner. The editor is in *this*
+   tree on purpose: style-mod mounts CodeMirror's base theme into the root it
+   resolves from the container (`editor.ts`), which is this shadow root, so the
+   `.cm-*` rules land where they are used. Only the result container is a slotted
+   light-DOM node, because VTable injects a *document-level* stylesheet that a
+   shadow boundary could not host (`sql.css` styles that one).
+
+   Theme colours arrive through the inherited `--ifm-*` custom properties;
+   box-sizing must be re-declared here because the host page's universal reset
+   does not cross the shadow boundary. */
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+:host {
+  display: block;
+  margin: 1rem 0;
+}
+
+.dfk-sql-code {
+  position: relative;
+}
+
+/* The editor and the buttons are in this same tree, so CodeMirror's own base
+   theme (mounted by style-mod into this shadow root, see `editor.ts`) and these
+   rules land in one cascade. Our selectors carry `.dfk-sql-editor`, so they
+   outrank CodeMirror's bare `.cm-*` ones whatever the sheet order turns out to
+   be. */
+.dfk-sql-editor {
+  border: 1px solid var(--ifm-global-border-color, #e0e0e0);
+  border-radius: var(--ifm-global-radius, 0.4rem);
+  overflow: hidden;
+  background: var(--ifm-background-surface-color, #fff);
+  font-size: var(--ifm-code-font-size, 95%);
+}
+
+.dfk-sql-editor .cm-editor {
+  outline: none;
+}
+
+/* --- Loading placeholder -------------------------------------------------- */
+
+/* The editor is a lazy `import()`; until the CodeMirror modules arrive (a few
+   hundred KB on a slow link) the box would be an empty outline. The ghost is one
+   bar per line of SQL, which is what the editor itself is — one
+   `line-height: 1.6` box per line — so the block does not resize when CodeMirror
+   takes over. `#setEditorPending` builds it and drops it again.
+
+   `sql/remark.ts` prerenders the very same bars for the longer window *before*
+   this component exists, and `sql.css` carries their copy of these two rules (a
+   shadow tree sees neither the document's rules nor its `@keyframes`): keep the
+   two in sync. */
+.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 + 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;
+}
+
+@keyframes dfk-sql-shimmer {
+  from {
+    background-position: 0% 0;
+  }
+  to {
+    background-position: 100% 0;
+  }
+}
+
+/* A bar that sweeps forever is decoration; readers who asked for less motion get
+   the static grey. Mirrored in `sql.css`. */
+@media (prefers-reduced-motion: reduce) {
+  .dfk-sql-editor-skeleton-line {
+    animation: none;
+  }
+}
+
+.dfk-sql-editor .cm-scroller {
+  font-family: var(--ifm-font-family-monospace, ui-monospace, SFMono-Regular,
+    Menlo, monospace);
+  line-height: 1.6;
+}
+
+/* The editor's vertical inset is CodeMirror's own (`padding: 4px 0` in its base
+   theme) and is deliberately left alone. ViewState reads the content's computed
+   `padding-top` with `parseInt` and re-applies it as the first gutter element's
+   `marginTop` (it arrives as the gutter's `above` offset), so an override that
+   is not a whole number of pixels — `0.4rem` is 6.4px, mirrored as 6px — leaves
+   the line numbers fractionally off, and padding `.cm-gutters` as well would
+   count the inset twice: the numbers then sit ~6px below the lines they
+   belong to. */
+
+/* Hover/focus-revealed, like the buttons on Docusaurus' own code blocks. The
+   cluster is inert while hidden so an invisible button is never a click target
+   in the middle of the code. */
+.dfk-sql-actions {
+  position: absolute;
+  top: 0.25rem;
+  right: 0.25rem;
+  z-index: 1;
+  display: flex;
+  align-items: center;
+  gap: 0.15rem;
+  padding: 0.1rem 0.2rem;
+  border-radius: var(--ifm-global-radius, 0.3rem);
+  background: var(--ifm-color-emphasis-100, #f5f5f5);
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.12s ease;
+}
+
+.dfk-sql-code:hover .dfk-sql-actions,
+.dfk-sql-code:focus-within .dfk-sql-actions,
+.dfk-sql-actions-busy {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+.dfk-sql-status {
+  padding: 0 0.25rem;
+  font-size: 0.72rem;
+  color: var(--ifm-color-emphasis-700, #666);
+  white-space: nowrap;
+}
+
+.dfk-sql-status:empty {
+  display: none;
+}
+
+/* --- Icon buttons and their tooltips ------------------------------------- */
+
+/* Duplicated in `sql.css`: these buttons live in this shadow tree, while the
+   fullscreen toggle a renderer parks in the result's tab strip lives in the
+   light DOM, where a shadow rule could not reach it. Keep both 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;
+}