Is 562 implement ux UI designed component section#63
Open
iimpulse wants to merge 62 commits into
Open
Conversation
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…esigned-component-section docs: add component page system design spec (IS-585)
…pressionChangedAfterChecked
Correct the tab structure (Overview/Properties/Theming; Variations, Usage, and Component Activity become Overview sections), switch content to source-of-truth generation (Compodoc properties, ?raw snippets, markdown prose), hand-authored theming CSS variables, drop the Activity tab and ngx-highlightjs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…562-implement-ux-ui-designed-component-section
Rework the progress-widget pilot to the approved design: - Tabs are Overview, Properties, Theming (was Overview/Variations/Usage/API) - Overview is a single scrolling page: header, variation sections, usage do/don't panels, and Component Activity - Properties tab replaces API; Theming tab lists overridable CSS variables - Left nav grouped by category (Navigation/Input/Messaging/Data Display/ Utilities) with a Help & Documentation link - Right TOC lists Summary + variations + Usage + Component Activity, with a Download Vignette button - Remove ngx-highlightjs; code blocks are plain styled <pre> with copy ComponentDoc reworked: category, description, theming, activity; api renamed to properties; group/overview removed. Content generation (Compodoc properties, ?raw snippets, markdown prose) deferred to a later stage. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Docs code blocks now use plain styled <pre>; the syntax-highlight libs are no longer referenced. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a Compodoc pipeline that extracts each component's inputs/outputs and JSDoc into a generated TS map (COMPONENT_PROPERTIES), consumed by the Properties tab. Removes the hand-authored properties for progress-widget so the table is sourced from the component's real signal inputs + JSDoc and cannot drift. - tools/generate-docs-properties.mjs + `pnpm docs:properties` - per-property JSDoc on ProgressWidgetComponent inputs - ComponentDoc gains compodocSymbol; properties is now an optional fallback Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The esbuild builder doesn't support `?raw` imports, so instead of copying example source we extract each snippet from the same demo template that renders it, via `snippet:<id>` marker comments. The code block is now the exact markup running in the live demo and cannot drift. - tools/generate-docs-snippets.mjs + `pnpm docs:snippets` (+ docs:generate) - doc-variations prefers COMPONENT_SNIPPETS[slug][id] - VariationDoc.code is now an optional fallback; removed hand-authored code Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Compodoc-generated Properties and marker-extracted snippets replace the ?raw approach (unsupported by the esbuild builder). Markdown dropped — Overview/Usage are structured to match the design. Update content-generation table, file layout, dependencies, conventions, and reference status. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Top navbar gets a Components entry routing to /components, which redirects to the progress-widget docs page. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Step-by-step guide covering per-input JSDoc, front-matter, showcase demo templates with snippet markers, registry + routes, pnpm docs:generate, and verification, with progress-widget as the reference. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the hand-rolled nav/anchor tab strip with PrimeNG's Tabs (p-tabs/p-tablist/p-tab). The active tab is derived from the route and tab changes navigate to /components/:slug/:tab. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Override PrimeNG Tabs to the design spec (node 2663:601): 20px/28px labels, active tab bold #0177b2 with a 2px blue active bar, inactive #636363, tablist bottom border #d9d9d9, and 16px/24px container padding. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Wrap the tabs so the reset reaches the p-tabs host (kills the themed background box), and recolor PrimeNG's own active bar (bottom baseline) instead of a per-tab border, which was rendering at the top. Verified against the Figma tablist. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Its purpose was undefined; dropping it until a real action is specified. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The height chain lacked min-height:0, so the whole page scrolled and the left nav + right TOC scrolled out of view. Add min-h-0/overflow so only the content pane scrolls; navbar, tabs, left nav, and the "On this page" TOC now stay in view (and TOC scroll-spy highlights the active section). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Scopes the first services-docs pass to the ontology service, chosen because both its implementations (Jax, OLS) hit real live public backends with no auth/mocking needed.
Verified Compodoc's actual JSON shape for libs/api-clients (doc.classes vs doc.injectables, methods key) empirically before writing the generator task, rather than assuming.
…ces too Widening DocsContextService to DocBase surfaced three call sites reading Components-specific fields (DocPropertiesComponent, DocThemingComponent, docs-shell's binding to DocsRightTocComponent) — narrowed each with an explicit cast back to ComponentDoc, since they're only ever rendered on a Components route.
ServiceDoc declares its shared fields locally (mirroring DocBase's shape) rather than importing @jax-data-science/component-docs, since libs/components already depends on libs/api-clients and an import in the other direction would create a circular project dependency. Structural typing keeps ServiceDoc assignable wherever DocBase is expected.
JaxOntologyService.search() builds its request URL synchronously via ontologyBaseResolver(), which throws before the observable is even subscribed if the async config fetch hasn't completed (or, as found during live verification, if config_location 404s — a pre-existing, separate issue in the library left untouched per explicit direction). Wrapping in defer() + catchError turns that into a real, visible error state in the UI instead of an uncaught exception during component construction — same "real behavior, not a mock" principle already used for AsyncTask's empty/error state.
Usage examples are now static code blocks only, no live HTTP calls. Services left-nav section lists services flat, without category headers, for now.
Content adapted from the repo README's Overview/Community sections. Adds a minimal GettingStartedShellComponent (left-nav + router-outlet only, no tab bar) since the left nav previously only rendered inside DocsShellComponent/ServicesShellComponent. Installation/About Echo/Citation links remain unbuilt for now — only Overview was requested.
Every service showcase now has the same shape (header + static usage examples + usage + activity, no live calls), so one component parameterized by whatever ServiceDoc is in context replaces the per-service showcase file. Removes showcase-ontology.component.*; adding a new service no longer requires a new showcase component.
Installation instructions now live in the Getting Started Overview page (npm package table) instead of a separate dead-linked page.
Also fixes generate-docs-methods.mjs: it was including private methods (e.g. ISADataService.buildUrl) in the Methods table since it read every entry in Compodoc's methods array with no visibility filter. Now excludes TypeScript's PrivateKeyword/ProtectedKeyword modifiers.
iimpulse
temporarily deployed
to
jax-cluster-dev-10--dev
GitHub Actions
Inactive
iimpulse
temporarily deployed
to
jax-cluster-dev-10--dev
GitHub Actions
Inactive
Adds "Creating a Component" and "Creating a Service" pages that render
the real docs/contributing-*.md files via marked, so the content can
never drift out of sync with the actual guides. Removes the dead
Citation/License link.
marked and @tailwindcss/typography both had to land as root
dependencies rather than demo-app-only: pnpm's per-package isolation
means a dependency declared only in apps/demo/package.json isn't
resolvable from the shared root tailwind.config.js, nor from Angular's
dev-server virtual vite-root (which resolves relative to the repo
root's real node_modules, not apps/demo's). Also required an explicit
esbuild loader entry (".md": "text") in apps/demo/project.json, since
Angular's production builder — unlike its Vite-based dev server —
doesn't auto-handle arbitrary `?raw` file extensions.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Builds out the new, generation-driven docs system for apps/demo (IS-562) — a component/service page is assembled from front-matter + JSDoc rather than hand-maintained markup, so the Properties/Methods tables and
code snippets can never drift from source. This branch takes it from a single pilot page (progress-widget) to full coverage of the Components section, a brand-new Services section, and a Getting Started
section, along with the tooling that generates each of their data-backed tabs.
What's in this PR
Components section — migrated all 6 remaining components
widget-error, auth, navbar, facet-search, asynctask, and progress-widget (pilot) each get per-property JSDoc, a .docs.ts front-matter, a showcase page with snippet-marked live demos, and left-nav/route
registration. Notable calls: facet-search uses static mock data instead of a dead legacy backend call; asynctask's demo shows the component's real empty/error state when no backend is reachable; fixed a jsdom
window.matchMedia gap needed by PrimeNG's Menubar.
Services section — new
Didn't exist before (just two dead links). Added a ServiceDoc model, a generated Methods tab (parallel to Properties), and one generic ServiceOverviewComponent reused by all 5 services (ontology, isa-data,
asynctask, snp-grid, mvar) — adding a service is now just front-matter + registration, no new component. Usage examples are static code blocks by design, after live-testing surfaced a real stale-config bug in
JaxOntologyService (left untouched; the page degrades gracefully).
Getting Started section — new
Overview page adapted from the README, its own minimal shell component, dead "Installation" link removed in favor of inline npm-install content.
Shared infra & docs
DocBase extracted so Components/Services share tab-content components; docs/contributing-a-component.md and docs/contributing-a-service.md kept accurate.