@walkeros/explorer 4.7.2 → 4.8.0-next-1791496487198

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # @walkeros/explorer
 
+## 4.8.0-next-1791496487198
+
+### Minor Changes
+
+- bf6221f: Explorer now ships the walkerOS design system. Import
+  `@walkeros/explorer/design/tokens.css` for colour, type, spacing, radius and
+  layer tokens (dark by default, light under `data-theme="light"`), the opt-in
+  `design/base.css`, the Tailwind v4 bridge `design/tailwind.css`, and typed
+  colour and font constants from `@walkeros/explorer/design`. A
+  `walkeros-design-check` command lints consuming code. Existing exports are
+  unchanged.
+- aa4bb8b: Add `Playground`: a tagged component, its event, an editable mapping
+  and the resulting gtag call side by side, on one real flow (`startFlow`, the
+  browser source scoped to a shadow root, and the gtag destination with a
+  stubbed `gtag`). `@walkeros/web-destination-gtag` is now a runtime dependency.
+
+### Patch Changes
+
+- 7132619: `@walkeros/explorer/design/components` gains `BrowserFrame`, a
+  browser window on the site theme around any page: an address field with the
+  URL, an optional reload button, a slot for the caller's actions and an
+  optional bookmarks row that marks the current page. It is sized by its caller
+  and styled by `@walkeros/explorer/styles.css`. `Icon` gains `lock`, `reload`
+  and `bookmark`.
+- d5cbc9c: New `@walkeros/explorer/design/components` export with `Button`,
+  `InlineCode` and `EventLegend`, styled by `@walkeros/explorer/styles.css`.
+  `Button` forwards tagging attributes to its element and accepts a router link
+  component.
+- d5cbc9c: `@walkeros/explorer/design/components` gains the building blocks of
+  the walkerOS home page: `Icon`, `InstallCommand`, `Card`, `Eyebrow`, `Stat`,
+  `Text`, `TextLink`, `CheckList`, `SectionHeading`, `ProblemCard`,
+  `FeatureItem`, `FaqItem`, `PlanCard`, `CaseCard`, `HighlightCard`, `Section`,
+  `CardGrid`, `Split`, `Cluster`, `Hero`, and the three home page demos
+  (`HeroTaggingViz`, `ArticleTeaserTracking`, `DestinationMappingViz`). Every
+  design component forwards tagging attributes to its root.
+- 01d86a5: Explorer components now read the walkerOS design tokens: import
+  `@walkeros/explorer/design/tokens.css` beside `styles.css`. The old theme
+  variables (`--bg-box`, `--color-text` and the rest) are removed. Code panels
+  are dark in both page themes. Removed exports: `lighthouseTheme`,
+  `registerLighthouseTheme`, `palenightTheme`, `registerPalenightTheme`, type
+  `ExplorerTheme`, and `registerAllThemes`, replaced by `registerTheme`.
+  `ELB_THEME_DARK` is now exported.
+- d5cbc9c: `@walkeros/explorer/design/tokens.css` now declares every type style
+  as CSS variables: `--type-<style>-size`, `-line-height`, `-weight`, `-family`
+  and, when the style sets one, `-tracking`. Components can take sizes and
+  weights from the design system instead of fixed values.
+- 7132619: The `PromotionPlayground` and `LiveCode` mapping examples show events
+  and results again, and every failure says so in the box it concerns. `Preview`
+  takes a `collector` instead of `elb` and captures the page's events through
+  it; its document carries the design tokens, base rules and design atom styles,
+  so the demo product card is built from `Card`, `PhotoPlaceholder`, `Text` and
+  `Button`. The Playground drops its separate Code box and the `labelCode` prop:
+  the Preview's HTML, CSS and JS tabs edit the page. New props: `placeholder`
+  and `error` on `CodeBox`, `error` on `Box`, `boxWidth` on `Grid` for one row
+  of fixed-width boxes.
+- 7132619: New `ViewSource` component: wrap a tagged element, hover it and
+  toggle to its live HTML with the `data-elb` attributes, edited in place. Back
+  in Visual the element renders your edit and walkerOS picks up the new tags; a
+  Reset icon restores the original. New `ToggleButton`: one button that names
+  the option a click switches to, at a fixed width.
+- a4b03ba: The five event colours (globals, context, entity, property, action)
+  now have a light-theme value that reads as text on light backgrounds. Their
+  constants in `@walkeros/explorer/design` are now `{ dark, light }` objects,
+  like every other themed colour; read `.dark` where the colour sits on a dark
+  ground.
+- Updated dependencies [7132619]
+- Updated dependencies [5593d7b]
+- Updated dependencies [421233d]
+- Updated dependencies [5593d7b]
+  - @walkeros/core@4.8.0-next-1791496487198
+  - @walkeros/web-destination-gtag@4.8.0-next-1791496487198
+  - @walkeros/collector@4.8.0-next-1791496487198
+  - @walkeros/web-core@4.8.0-next-1791496487198
+  - @walkeros/web-source-browser@4.8.0-next-1791496487198
+
 ## 4.7.2
 
 ### Patch Changes

package/README.md

@@ -21,21 +21,50 @@ npm install @walkeros/explorer
 
 ## Quick start
 
-Import a component and the stylesheet:
+Import the design tokens once per page, then explorer's styles and a component:
 
 ```tsx
-import { MappingDemo } from '@walkeros/explorer';
+import '@walkeros/explorer/design/tokens.css';
 import '@walkeros/explorer/styles.css';
+import { CodeBox } from '@walkeros/explorer';
 
-<MappingDemo
-  input='{"name": "example"}'
-  config='{"transform": "uppercase"}'
-  fn={async (input, config) => transform(input, config)}
-/>;
+<CodeBox code={'{ "name": "page view" }'} language="json" label="Event" />;
 ```
 
-Switch themes via the `data-theme` attribute on a parent element (`light` or
-`dark`).
+In a Tailwind v4 build, import `@walkeros/explorer/design/tailwind.css` after
+`@import "tailwindcss"` instead of `tokens.css`: it brings the tokens, a utility
+for every design colour and type style, `max-w-*` widths in px and `transition`
+utilities on the design motion. `@walkeros/explorer/design/base.css` adds
+optional page-wide base rules (font, colours, focus ring, selection).
+
+## Themes
+
+Set `data-theme="dark"` (the default) or `data-theme="light"` on the page root.
+Code surfaces (`CodeBox`, `CodeView`, `Code`, the preview) stay dark in both
+themes. Monaco uses one code theme; `Code` and `CodeBox` register it themselves.
+A Monaco editor of your own registers it with:
+
+```ts
+import { registerTheme, ELB_THEME_DARK } from '@walkeros/explorer';
+
+registerTheme(monaco);
+monaco.editor.setTheme(ELB_THEME_DARK);
+```
+
+## Design system
+
+Explorer ships the walkerOS design system:
+
+| Import                                   | What                                                                                                                         |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `@walkeros/explorer/design/tokens.css`   | The design tokens as CSS custom properties                                                                                   |
+| `@walkeros/explorer/design/tailwind.css` | The tokens as a Tailwind v4 theme                                                                                            |
+| `@walkeros/explorer/design/base.css`     | Optional base rules for a whole page                                                                                         |
+| `@walkeros/explorer/design`              | The token values as constants (colours, fonts, type styles, motion), for code that cannot read CSS variables                 |
+| `@walkeros/explorer/design/components`   | React building blocks of walkerOS pages (`Button`, `InlineCode`, `EventLegend` and more), with no Monaco or walkerOS runtime |
+
+The `walkeros-design-check` command checks a package's own styles against the
+design system.
 
 ## Documentation
 

package/bin/walkeros-design-check.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// Committed so npm links the bin at install time, before the first build. The
+// checker itself is built into dist/design, beside the design CSS it reads.
+import { existsSync } from 'node:fs';
+
+const checker = new URL('../dist/design/check.mjs', import.meta.url);
+
+if (existsSync(checker)) {
+  await import(checker.href);
+} else {
+  process.stderr.write(
+    'walkeros-design-check: dist/design/check.mjs is missing, run `npm run build` in apps/explorer\n',
+  );
+  process.exitCode = 2;
+}

package/dist/design/base.css

@@ -0,0 +1,54 @@
+/*
+ * walkerOS base rules. Opt-in and global: import once per page after
+ * tokens.css. Explorer's own reset stays scoped to .elb-explorer.
+ */
+@layer base {
+  /*
+   * tokens.css sets --motion to 0ms for reduced motion; this guard also stops
+   * animations, transitions with their own durations and smooth scrolling.
+   */
+  @media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.01ms !important;
+      scroll-behavior: auto !important;
+    }
+  }
+
+  :root,
+  :host,
+  [data-theme='dark'] {
+    color-scheme: dark;
+  }
+
+  [data-theme='light'] {
+    color-scheme: light;
+  }
+
+  /* Islands recompute these from their own theme's tokens. */
+  html,
+  :host,
+  [data-theme] {
+    font-family: var(--font-sans);
+    color: var(--fg);
+    scrollbar-color: var(--border-strong) transparent;
+  }
+
+  /* Only the page paints a ground; a background on :host would cover the customer page. */
+  html {
+    background-color: var(--bg);
+  }
+
+  :focus-visible {
+    outline: 2px solid var(--focus);
+    outline-offset: 3px;
+  }
+
+  ::selection {
+    background-color: var(--primary);
+    color: var(--on-primary);
+  }
+}