Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@ jobs:
node-version: 24
cache: npm
- run: npm ci
- name: Compile the pinned Ionic component reference
run: npm run docs:sync:ionic
- name: Refresh and verify public sponsor data
run: |
npm run sponsors:generate
Expand Down
2 changes: 2 additions & 0 deletions .github/workflows/deploy-cloudflare.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ jobs:
node-version: 24
cache: npm
- run: npm ci
- name: Compile the pinned Ionic component reference
run: npm run docs:sync:ionic
- name: Refresh all public sponsors before building
run: npm run sponsors:generate
env:
Expand Down
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -50,3 +50,7 @@ Thumbs.db
/projects/docs/public/assets/theme-preview/*.js
/projects/docs/public/assets/theme-preview/*.css
/projects/docs/public/assets/theme-preview/markup-*.html

# Compiled by docs:sync:ionic before testing and building the portal.
/projects/docs/public/assets/ionic-components/
/projects/docs/src/app/generated/ionic-components/
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,3 +61,5 @@ checks that the committed snapshot is current. The generator excludes private
sponsorships and follows every pagination cursor. If fetching fails, deployment stops rather
than publishing a stale list. Local builds use the committed snapshot; to refresh it, run
`GITHUB_TOKEN=<token> npm run sponsors:generate` with a GitHub token provided through the environment.

On a fresh checkout, run `npm run docs:sync:ionic` after installing dependencies to generate the [Ionic component reference](scripts/ionic-preview/README.md).
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
"packageManager": "npm@11.7.0",
"scripts": {
"ng": "ng",
"docs:sync:ionic": "node scripts/preview-ionic-components.mjs",
"docs:generate": "npm run docs:generate:content && node scripts/build-theme-preview.mjs",
"docs:generate:content": "tsx scripts/generate-docs.ts",
"seo:audit": "tsx scripts/seo-audit.ts",
Expand Down
24 changes: 24 additions & 0 deletions projects/docs/src/app/app.css
Original file line number Diff line number Diff line change
Expand Up @@ -199,3 +199,27 @@
color: #f8fafc;
font-size: 1rem;
}

.component-reference {
padding-bottom: 0;
}
.component-nav-entry {
display: flex;
align-items: center;
justify-content: space-between;
width: 100%;
min-height: 44px;
padding: 10px 12px;
border-radius: 8px;
border: 0;
background: transparent;
color: #475569;
font: inherit;
font-size: 13px;
cursor: pointer;
}
.component-nav-entry:hover,
.component-nav-entry:focus-visible {
color: #1767d2;
background: #eff6ff;
}
28 changes: 27 additions & 1 deletion projects/docs/src/app/app.html
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,30 @@ <h2 id="migration-navigation-title">{{ guideCopy.otherGuides }}</h2>
</section>
}
</nav>
<section
class="reference-navigation component-reference"
aria-labelledby="component-reference-title"
>
<h2 id="component-reference-title" i18n="@@componentReferenceTitle">
Component reference
</h2>
<button
id="open-components"
class="component-nav-entry"
type="button"
(click)="openComponents()"
>
<span i18n="@@ionicComponentsNav">Ionic components</span>
<svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">
<path
d="m6 3 5 5-5 5"
stroke="currentColor"
stroke-linecap="round"
stroke-linejoin="round"
/>
</svg>
</button>
</section>
<section class="reference-navigation" aria-labelledby="package-reference-title">
<h2 id="package-reference-title">{{ guideCopy.reference }}</h2>
<app-library-picker
Expand All @@ -173,7 +197,9 @@ <h2 id="package-reference-title">{{ guideCopy.reference }}</h2>
[attr.inert]="showingLibraries() ? '' : null"
[attr.aria-hidden]="showingLibraries() ? 'true' : null"
>
@if (navigationProject(); as project) {
@if (componentPanel()) {
<app-ionic-components-navigation (back)="leaveComponents()" />
} @else if (navigationProject(); as project) {
<app-project-navigation
[project]="project"
[categoryLabel]="guideCopy.reference"
Expand Down
20 changes: 19 additions & 1 deletion projects/docs/src/app/app.routes.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { GUIDE_CHAPTERS } from '../../../../shared/guide-navigation';
import { inject } from '@angular/core';
import { inject, LOCALE_ID } from '@angular/core';
import { Router, Routes } from '@angular/router';
import { DocsPageComponent } from './docs/docs-page';
import { LandingPageComponent } from './docs/landing-page';
Expand All @@ -8,6 +8,10 @@ import { PluginIndexComponent } from './docs/plugin-index';
import { projectCatalog } from './docs/docs-data';
import { projectResolver } from './docs/project.resolver';

import { catalog as ionicComponents } from './generated/ionic-components/catalog';

const componentPage = () =>
import('./docs/ionic-components-page').then((m) => m.IonicComponentsPage);
const portalProjects = projectCatalog.filter((project) => !project.hostedUrl);

const projectRoutes: Routes = portalProjects.flatMap((project) => [
Expand Down Expand Up @@ -62,6 +66,20 @@ export const routes: Routes = [
data: { chapter: chapter.id },
loadComponent: () => import('./docs/guide-page').then((module) => module.GuidePageComponent),
})),
{ path: 'components', loadComponent: componentPage },
...ionicComponents.map((item) => ({
path: 'components/' + item.slug,
data: { slug: item.slug },
resolve: {
blocks: () =>
inject(LOCALE_ID).split('-')[0] === 'ja'
? import('./generated/ionic-components/ja/catalog').then(({ catalog }) =>
catalog.find((entry) => entry.slug === item.slug)!.load(),
)
: item.load(),
},
loadComponent: componentPage,
})),
...projectLegacyRoutes,
...projectRoutes,
{ path: 'not-found', component: NotFoundComponent },
Expand Down
7 changes: 5 additions & 2 deletions projects/docs/src/app/app.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,10 @@ describe('App', () => {
);
}
expect(compiled.querySelector('.guide-navigation a[href="/standard-setup"]')).not.toBeNull();
expect(compiled.querySelector('.reference-navigation h2')?.textContent).toContain(
expect(compiled.querySelector('#component-reference-title')?.textContent).toContain(
'Component reference',
);
expect(compiled.querySelector('#package-reference-title')?.textContent).toContain(
'Package reference',
);
expect(compiled.querySelector('details.reference-navigation')).toBeNull();
Expand Down Expand Up @@ -519,7 +522,7 @@ describe('App', () => {
fixture.detectChanges();
const compiled = fixture.nativeElement as HTMLElement;
expect(compiled.querySelector('.docs-rail')).toBeNull();
const reference = compiled.querySelector('.reference-navigation')!;
const reference = compiled.querySelector('section[aria-labelledby="package-reference-title"]')!;
expect(reference.querySelectorAll('app-library-picker a')).toHaveLength(
projectsForLocale('en').filter((project) => !project.hostedUrl).length,
);
Expand Down
33 changes: 31 additions & 2 deletions projects/docs/src/app/app.ts
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ import {
} from '@angular/router';
import { ProjectSummary, projectGroupsForLocale, projectsForLocale } from './docs/docs-data';
import { LibraryPicker } from './docs/library-picker';
import { IonicComponentsNavigation } from './docs/ionic-components-navigation';
import { ProjectNavigation } from './docs/project-navigation';
import { canonicalHomePath, localizedPublicPath } from './locale-path';
import { FooterSponsors } from './footer-sponsors/footer-sponsors';
Expand Down Expand Up @@ -61,6 +62,7 @@ export const INITIAL_DOCS_URL = makeStateKey<string>('rdlabo-docs-initial-url');
RouterLink,
LibraryPicker,
ProjectNavigation,
IonicComponentsNavigation,
LanguageMenu,
FooterSponsors,
],
Expand Down Expand Up @@ -137,8 +139,32 @@ export class App {
protected readonly isSupport = computed(() => this.currentUrl().split(/[?#]/)[0] === '/support');
protected readonly activeProject = computed(() => this.#projectForUrl(this.currentUrl()));
protected readonly navigationProject = computed(() => this.#projectForUrl(this.navigationUrl()));
protected readonly browsingComponents = signal(false);
protected readonly componentRoute = computed(() =>
/^\/components(?:[/?#]|$)/.test(this.navigationUrl()),
);
protected readonly componentPanel = computed(
() => this.browsingComponents() || this.componentRoute(),
);
protected openComponents(): void {
this.#menuRevision++;
this.libraryPickerOpen.set(false);
this.browsingComponents.set(true);
this.#focusProjectNavigation();
}
protected leaveComponents(): void {
this.browsingComponents.set(false);
this.openLibraryPicker();
afterNextRender(
() =>
this.#focusNavigationLink(
this.docsSidebar?.nativeElement.querySelector('#open-components'),
),
{ injector: this.#injector },
);
}
protected readonly showingLibraries = computed(
() => !this.navigationProject() || this.libraryPickerOpen(),
() => (!this.navigationProject() && !this.componentPanel()) || this.libraryPickerOpen(),
);

constructor() {
Expand Down Expand Up @@ -249,6 +275,7 @@ export class App {
}
if (!(event instanceof NavigationEnd) || event.id !== this.#navigationId) return;
const pending = this.pendingNavigation();
this.browsingComponents.set(false);
this.currentUrl.set(event.urlAfterRedirects);
this.pendingNavigation.set(null);
this.navigationError.set(null);
Expand Down Expand Up @@ -326,6 +353,7 @@ export class App {
}
this.#menuRevision++;
this.menuOpen.set(false);
this.browsingComponents.set(false);
this.libraryPickerOpen.set(false);
if (returnFocus) queueMicrotask(() => this.menuButton?.nativeElement.focus());
}
Expand Down Expand Up @@ -445,7 +473,8 @@ export class App {
this.#document.querySelector('dialog[open], app-language-menu details[open]')
)
return;
if (this.navigationProject() && this.libraryPickerOpen()) this.closeLibraryPicker();
if ((this.navigationProject() || this.componentRoute()) && this.libraryPickerOpen())
this.closeLibraryPicker();
else if (this.mobileLayout()) this.closeMenu();
}

Expand Down
30 changes: 30 additions & 0 deletions projects/docs/src/app/docs/ionic-article-tabs.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
import { Component, input, linkedSignal } from '@angular/core';

export interface ArticleTabs {
kind: 'tabs';
panels: { label: string; html: string }[];
}

@Component({
selector: 'app-ionic-article-tabs',
template: `
<div class="choices">
@for (panel of group().panels; track panel.label) {
<button type="button" [attr.aria-pressed]="active() === panel" (click)="active.set(panel)">{{ panel.label }}</button>
}
</div>
<div class="code" [innerHTML]="active().html"></div>
`,
styles: `
:host {display:block;overflow:hidden;margin:1rem 0 2rem;border-radius:.75rem;background:#f5f7fb}
.choices {display:flex;flex-wrap:wrap;padding:.375rem;gap:.25rem;background:#e9edf4}
button {border:0;border-radius:.5rem;background:transparent;color:#46556b;font:600 .875rem/1.5 system-ui;padding:.45rem .9rem;cursor:pointer}
button[aria-pressed=true] {background:white;color:#175bb3}
:host ::ng-deep .code pre {background:transparent;color:#203047;margin:0;padding:clamp(1rem,3vw,2rem);overflow:auto;border:0}
:host ::ng-deep .code pre code {background:transparent;color:inherit;font:400 .875rem/1.65 ui-monospace,SFMono-Regular,Menlo,monospace;white-space:pre}
`,
})
export class IonicArticleTabs {
readonly group = input.required<ArticleTabs>();
readonly active = linkedSignal(() => this.group().panels[0]);
}
87 changes: 87 additions & 0 deletions projects/docs/src/app/docs/ionic-component-demo.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
import { Component, computed, ElementRef, inject, input, linkedSignal, signal, viewChild } from '@angular/core';
import { DomSanitizer } from '@angular/platform-browser';

export interface IonicDemo {
kind: 'demo';
src: string;
mode: string;
console: boolean;
examples: { name: string; files: { name: string; html: string }[] }[];
}
@Component({
selector: 'app-ionic-component-demo',
host: { '(window:message)': 'receive($event)' },
template: `
<section class="example">
<div class="toolbar">
<div class="controls" aria-label="Example language">
@for (ex of demo().examples; track ex.name) {
<button type="button" [attr.aria-pressed]="example() === ex" (click)="example.set(ex)">{{ names[ex.name] || ex.name }}</button>
}
</div>
<div class="controls" aria-label="Theme">
@for (t of themes; track t.key) {
<button type="button" [disabled]="demo().mode && demo().mode !== t.mode"
[attr.aria-pressed]="theme() === t.key" (click)="choose(t.key)">{{ t.label }}</button>
}
</div>
</div>
<iframe #frame [src]="url()" title="Component demo" loading="lazy"></iframe>
@if (demo().console) { <output>{{ log() }}</output> }
</section>
<div class="code">
@if (example().files.length > 1) {
<div class="files" role="group" aria-label="Source file">
@for (f of example().files; track f.name) {
<button type="button" [attr.aria-pressed]="file() === f" [title]="f.name" (click)="file.set(f)">
<span class="ext" aria-hidden="true">{{ f.name.split('.').pop() }}</span><span class="full-path">{{ f.name }}</span><span class="short-path">{{ f.name.split('/').pop() }}</span>
</button>
}
</div>
}
<pre tabindex="0"><code [innerHTML]="file().html"></code></pre>
</div>
`,
styles: `
:host { display:block;margin:1.5rem 0 2.5rem;color:#172033 }
.example,.code{overflow:hidden;border:1px solid #dbe3ed;border-radius:.75rem}
.code{margin-top:.75rem;background:#f6f8fb}
.controls{display:flex;gap:.15rem;flex-wrap:wrap;padding:.4rem .55rem;background:white;border-bottom:1px solid #e2e8f0}
button{background:transparent;border:0;border-radius:2rem;padding:.5rem .8rem;color:#475569;font:600 .875rem/1.5 system-ui;cursor:pointer}
button[aria-pressed=true]{background:#e6efff;color:#1459b8}button:disabled{opacity:.45}
iframe{width:100%;height:clamp(18rem,49vh,27rem);display:block;border:0}
.toolbar{display:flex;flex-wrap:wrap;align-items:center;border-bottom:1px solid #dbe3ed}
.toolbar .controls{border:0}
.toolbar .controls + .controls{border-inline-start:1px solid #dbe3ed}
.code{background:#f5f7fb;border:0}
.files{background:#e9edf4;display:flex;overflow-x:auto}
.files button{display:flex;align-items:center;gap:.55rem;flex:none;white-space:nowrap;border-radius:0;color:#46556b;padding:.75rem 1rem;font-size:.8rem;font-weight:500}
.files button[aria-pressed=true]{background:#f5f7fb;color:#172943;box-shadow:inset 0 2px #2866bf}
.short-path{display:none}
@media(max-width:600px){.files .full-path,.files .ext{display:none}.files .short-path{display:inline}.files button{padding:.75rem .65rem}}
.ext{font:700 .7rem/1 monospace;color:#225bb0;text-transform:uppercase}
.code pre{background:transparent;color:#203047;margin:0;padding:clamp(1rem,3vw,2rem);overflow:auto;border:0;border-radius:0}
.code pre code{font:400 .875rem/1.65 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;background:transparent;color:inherit;padding:0;white-space:pre}
output{display:block;padding:.65rem 1rem;font:.8rem/1.5 monospace;color:#475569}
output:empty{display:none}
@media(max-width:600px){.toolbar .controls{width:100%}.toolbar .controls + .controls{border-inline-start:0;border-top:1px solid #edf0f4}}

`,
})
export class IonicComponentDemo {
readonly demo = input.required<IonicDemo>();
readonly themes = [{key:'ios27',mode:'ios',label:'iOS 27'},{key:'ios26',mode:'ios',label:'iOS 26'},{key:'md',mode:'md',label:'MD3'}];
readonly names: Record<string,string> = {angular:'Angular',javascript:'JavaScript',react:'React',vue:'Vue'};
readonly theme = linkedSignal<string>(() => this.demo().mode === 'md' ? 'md' : 'ios27');
readonly example = linkedSignal(() => this.demo().examples.find(e => e.name === 'angular') ?? this.demo().examples[0]);
readonly file = linkedSignal(() => this.example().files[0]);
readonly log = signal('');
readonly frame = viewChild<ElementRef<HTMLIFrameElement>>('frame');
readonly #sanitizer = inject(DomSanitizer);
readonly url = computed(() => this.#sanitizer.bypassSecurityTrustResourceUrl(
'/assets/ionic-components/'+this.demo().src+'?ionic:mode='+(this.theme()==='md'?'md':'ios')+'&theme='+this.theme()));
choose(theme: string) { this.log.set(''); this.theme.set(theme); }
receive(event: MessageEvent) {
if (this.demo().console && event.source === this.frame()?.nativeElement.contentWindow && event.origin === location.origin && typeof event.data?.ionicDemoLog === 'string') this.log.set(event.data.ionicDemoLog);
}
}
Loading
Loading