From 4ab9ed1d133842f65134279954fe392c483d9767 Mon Sep 17 00:00:00 2001 From: desig9stein Date: Thu, 9 Jul 2026 11:36:11 +0300 Subject: [PATCH 1/7] feat(docs): Add skill for documentation audit --- .claude/skills/igniteui-doc-topics/SKILL.md | 135 +++++++ .../references/audit-rubric.md | 156 +++++++++ .../references/diataxis-cheatsheet.md | 72 ++++ .../references/house-style.md | 329 ++++++++++++++++++ 4 files changed, 692 insertions(+) create mode 100644 .claude/skills/igniteui-doc-topics/SKILL.md create mode 100644 .claude/skills/igniteui-doc-topics/references/audit-rubric.md create mode 100644 .claude/skills/igniteui-doc-topics/references/diataxis-cheatsheet.md create mode 100644 .claude/skills/igniteui-doc-topics/references/house-style.md diff --git a/.claude/skills/igniteui-doc-topics/SKILL.md b/.claude/skills/igniteui-doc-topics/SKILL.md new file mode 100644 index 0000000000..976b831ce1 --- /dev/null +++ b/.claude/skills/igniteui-doc-topics/SKILL.md @@ -0,0 +1,135 @@ +--- +name: igniteui-doc-topics +description: >- + Author or audit Ignite UI documentation topics — component pages, how-to guides, conceptual + overviews, and category indexes — for both the Angular doc set and the cross-platform (React / + Web Components / Blazor) doc set. Applies the Diátaxis framework mapped onto Ignite UI's house + templates: canonical section order, fixed heading names, frontmatter (including `llms.description` + and the `relatedComponents` trigger), `.mdx` sample embeds, and per-framework token/PlatformBlock + mechanics. Use this whenever someone asks to write, draft, create, review, audit, fix, or + standardize a documentation topic, tutorial, guide, reference page, or concept overview for Ignite + UI — even if they just say "write docs for the X component" or "review this topic" without naming + Diátaxis or the templates. Also use it when deciding what *kind* of documentation a page should be, + or when a topic mixes tutorial / how-to / reference / explanation content that should be separated. +--- + +# Ignite UI doc topics + +Write and audit Ignite UI documentation topics so every page has the same predictable shape — easy +for developers to read and for AI assistants to answer from. The engine is **Diátaxis** (four +documentation modes) applied through **Ignite UI's house templates**. + +## Two modes of operation + +- **Create** — draft a new topic (component, concept/guide, or category/index) to the standard. +- **Audit** — review an existing topic against the standard and return an issues-and-fixes report. + +Detect which from the request ("write/draft/create" → Create; "review/audit/check/fix/standardize" → +Audit). If a topic file or content is supplied, default to Audit unless they ask for a rewrite. + +## Reference files — load what the task needs + +- `references/diataxis-cheatsheet.md` — the four modes + the compass. Load when classifying a topic + or diagnosing mode-bleed. +- `references/house-style.md` — sections, order, naming, frontmatter, sample/token mechanics, both + doc sets. Load for **every** create or audit. +- `references/audit-rubric.md` — the checkable rules + report format. Load for **every** audit. + +Read `house-style.md` before writing or judging any topic — it carries the mechanical details +(frontmatter fields, ``/`` syntax, Angular-vs-xplat differences) that aren't +in this file. + +## Step 0 — Classify with the compass (always first) + +Before writing or auditing, decide what *kind* of documentation the page is, using the compass from +the cheat-sheet: + +> **action or cognition?** × **acquisition (study) or application (work)?** +> → tutorial · how-to · reference · explanation + +- A **component page** is a *composite* (see below). +- A **concept / guide overview** is **explanation**. +- A **category / index overview** is **reference/navigation** (a map). +- A standalone **"How to …" article** is a **how-to guide** — keep it single-mode. + +If a request is ambiguous ("document X"), state which topic type you're producing and why, in one +line, before proceeding. + +## The composite-topic principle (the heart of this skill) + +Pure Diátaxis says keep the four modes in **separate** documents. Ignite UI **component topics +deliberately don't** — one page carries decision guidance (Overview), a live demo, a how-to +(Getting Started/Usage), do/don't guidance (Best Practices), and reference tables +(Properties/Methods/Events). That is fine **because each *section* owns exactly one mode.** The rule +that makes it work: + +> **One section, one mode. No mode-bleed.** Each section stays in its assigned Diátaxis mode; when a +> second mode wants in, move it to the section that owns it and cross-link. + +Section → mode map (full contents in `house-style.md`): + +| Section | Mode | Stays out of | +|---|---|---| +| Overview: When to Use / When Not to Use | **explanation** | install steps, API detail | +| Live Demo | demonstration (action) | prose/explanation | +| Anatomy: visual + DOM tree / skeleton | orientation (reference) | opinion, install steps | +| Getting Started, Usage | **how-to** | *why* explanations, exhaustive option lists | +| Best Practices: do/don't guidance | **explanation** | install steps, code, API detail | +| Properties / Methods / Events | **reference** | instructions, opinion | +| Styling (`### Sass Theming`, `### Tailwind`, …) | how-to (steps) + reference (tables) | conceptual essays | +| Accessibility | reference (keyboard/ARIA/compliance tables) | tutorials, marketing, unverified conformance claims | +| Troubleshooting | how-to (cause → fix) | background theory | +| API References / Dependencies / Additional Resources | reference / navigation | new teaching | + +Concrete mode-bleed to catch: a *why* paragraph inside **Usage** (→ move to When to Use or a concept +topic, link back); "how to build X" prose inside **Properties** (→ move to Usage; keep the table +descriptive); an exhaustive option list written out in **Usage** prose (→ move to the table). The +cheat-sheet's "two classic confusions" section explains the reasoning. + +## Create workflow + +1. **Classify** (Step 0). Name the topic type. +2. **Pick the doc set & framework.** Angular set = its own file, plain prose. xplat set = one file + for React/WC/Blazor using `{Platform}`/`{ProductName}` tokens and ``. Load + the relevant details from `house-style.md`. +3. **Write frontmatter first** — `title`, `description` (answer-shaped, ≤~160 chars), `keywords`, + `license`, `llms.description`, `mentionedTypes` (xplat), and `relatedComponents` if the component + has close siblings (this lets **Overview**'s **When Not to Use** sub-heading name the specific + sibling instead of speaking generically). +4. **Lay out the canonical sections** in order for that topic type, required ones always present. + Feature-specific content goes as sub-headings under **Usage**, never as new top-level sections. +5. **Fill each section in its mode.** Lead every section with one plain, specific sentence. Put + reference in tables. Embed exactly one top ``, then Usage samples only for distinct tasks + (soft max 5/page). Phrase When-Not-to-Use and Troubleshooting as the reader's real questions. +6. **Self-check against the rubric** before presenting — especially mode-bleed (C-checks) and + metadata (D-checks). Fix, then deliver the `.mdx`. + +## Audit workflow + +1. **Classify** the topic and identify its doc set (Angular vs xplat) and type. +2. **Run every check** in `references/audit-rubric.md` — structure/order (A), naming (B), Diátaxis + mode integrity (C), metadata/AI-readiness (D), samples/links (E). For mode integrity, run the + compass on each section and flag drift. +3. **Report** in the rubric's exact format: Verdict → Summary → Findings (each with Where / Issue / + Principle / Fix) → Quick wins. Order findings Error → Warning → Suggestion. +4. Keep every **Fix** concrete and applyable (the corrected heading, the sentence to move, the table + to add). If the topic is already clean, say so and note what it does well — don't invent problems. + +## Grounding notes + +- The live `vnext` repo is **pre-standardization**: expect drifted headings (`## Angular Rating + Example`, `## Configuration`) and a missing `relatedComponents` field. Author to the **target** + standard; audit against it while recognizing current reality. +- **Invent no verifiable identifier (zero-risk rule).** Never emit a guessed tag, class, package, + property, method, event, CSS part, or theming variable — a plausible-but-wrong name a reader copies is + worse than a visible gap. Use an identifier only when verified (typed API source, an existing topic, + or the user); otherwise write `‹VERIFY: …›`. For Properties/Methods/Events, emit the fixed column + headers plus a build-injection note and leave the rows to the generator. React/Blazor wrapper symbols + resolve to the `igc` core — prefer verified `igc` usage and mark unconfirmed wrapper names `‹VERIFY:…›`. + (Full detail in `house-style.md` → "Never fabricate API identifiers".) +- Prefer paraphrase and the standard section names over copying any existing topic's prose verbatim. +- **Write in one voice and verify every claim** (see house-style → *Voice & tone* and *Verify every + claim against the component*): instruct in the imperative/second person, and check every factual + statement — defaults, behavior, version support, DOM — against the component's typed source or the + official API/framework docs before writing it or recommending it as an edit. Don't "correct" prose + into a plausible claim you haven't verified. diff --git a/.claude/skills/igniteui-doc-topics/references/audit-rubric.md b/.claude/skills/igniteui-doc-topics/references/audit-rubric.md new file mode 100644 index 0000000000..3dbc1bca03 --- /dev/null +++ b/.claude/skills/igniteui-doc-topics/references/audit-rubric.md @@ -0,0 +1,156 @@ +# Audit rubric + +The checkable rules for **audit mode**, and the report format to produce. Every finding maps to a +concrete rule below (structure, naming, Diátaxis mode, or metadata) and to a fix. Detail lives in +`house-style.md`; the *why* behind mode findings lives in `diataxis-cheatsheet.md`. + +## Severity + +- **Error** — breaks the standard or misleads readers/AI. Must fix. +- **Warning** — drift or a gap that degrades quality. Should fix. +- **Suggestion** — polish; author's judgment. + +## Checks + +### A. Structure & order +- A1 (Error) A required section is missing (Overview, Live Demo, Getting Started, Usage, + Best Practices, Properties, Accessibility, API References, Additional Resources on a component + topic). +- A2 (Warning) Sections are present but out of the canonical order. +- A3 (Warning) A conditional section sits in the wrong slot. +- A4 (Error) A feature-specific top-level `##` exists that should be a sub-heading under **Usage**. +- A5 (Error) **Overview** is not the first section after the title/definition, or **Live Demo** is + missing or doesn't immediately follow **Overview**. +- A6 (Suggestion) >10 live samples on one page (soft cap) — consider splitting. Up to 10 is fine; + only flag when a page clearly sprawls past that. +- A7 (Warning) **When to Use / When Not to Use** are not `###` sub-headings under the `## Overview` + section — e.g. they appear as top-level `##`, or are still nested under **Anatomy** (the + pre-revision slot). +- A8 (Suggestion) **Anatomy** is missing its opening screenshot/GIF (or a `{/* TODO */}` marker for a + not-yet-available asset), or is missing the DOM tree / skeleton. +- A9 (Warning) **Accessibility** is missing one of its three required `###` sub-sections — + **Keyboard Interaction**, **Screen Readers / ARIA**, **Accessibility Compliance** — or has them out + of order. +- A10 (Warning) **Best Practices** contains install steps, code snippets, a property table, or other + reference/how-to content that belongs in Usage, Properties, or Accessibility instead of do/don't + guidance. + +### B. Naming +- B1 (Warning) A heading uses a drifted name with a standard equivalent (see reconciliation table). + Report both: `"Configuration" → Properties`. +- B2 (Warning) Non-standard one-off heading (e.g. `## Angular Rating Example`) → map to standard. +- B3 (Suggestion) Singular/plural or casing mismatch (`API Reference` → `API References`). +- B4 (Warning) H1 carries a framework prefix or an "Overview" suffix → standard H1 is + `‹Component› Component` (e.g. `# Angular Avatar Component Overview` → `# Avatar Component`). +- B5 (Warning) A **Usage** sub-heading repeats the component name (`### Avatar Shape` → `### Shape`). + +### C. Diátaxis mode integrity (mode-bleed) +Run the compass on each section; flag content that has drifted out of the section's assigned mode. +- C1 (Warning) **Explanation inside Usage/Getting Started** ("The reason this works is…") — move to + When to Use / a concept topic and link. +- C2 (Warning) **Instruction inside a reference section** (Properties/Methods/Events telling the + reader *how to* build something) — move to Usage; keep the table descriptive. +- C3 (Warning) **Reference dumped into Usage** (exhaustive option lists in prose) — move to the table. +- C4 (Warning) **When to Use that only says when to *use*** it, never when *not* to — the + When-Not-to-Use redirect is the high-value half. +- C5 (Suggestion) Tutorial-style hand-holding in a how-to (or vice-versa) — match the audience. +- C6 (Warning) **Styling content inside Usage** (CSS-var overrides, `color`/background + snippets) — move to the **Styling** section; Styling should also open with a `` of the result. +- C7 (Warning) **Usage doesn't cover every public input**, or documents each option in isolation + instead of stating the behavioral relationship once (e.g. the content-type priority). +- C8 (Warning) **Best Practices drifts into another mode** — install/code steps (belongs in Getting + Started/Usage), an exhaustive option table (belongs in Properties), or conformance claims (belongs + in Accessibility) instead of do/don't guidance. + +### D. Metadata & AI-readiness +- D1 (Warning) `relatedComponents` is set but **Overview**'s **When Not to Use** doesn't name the + specific sibling(s) by name and link them — or vice-versa, it names a sibling that isn't listed in + `relatedComponents`. +- D2 (Warning) Missing/weak `description` or `llms.description` (not answer-shaped, or >~160 chars). +- D3 (Warning) Section opens with no plain lead sentence, or with empty boilerplate. +- D4 (Warning) A section relies on "as mentioned above" / isn't self-contained. +- D5 (Warning) Properties/Methods/Events appear hand-written rather than from the typed source. +- D6 (Suggestion) Styling variables undocumented where the component is themeable. +- D7 (Warning) xplat: hard-coded framework name where a `{Platform}`/`{ProductName}` token belongs, or + framework-specific content not wrapped in ``. +- D8 (Error) An API identifier (tag, class, package, property, method, event, CSS part, theming + variable) appears to be fabricated/unverifiable, or an unresolved `‹VERIFY:…›` placeholder was left + in. Reference values must trace to the typed API source. +- D9 (Error) A **claim** contradicts or isn't verifiable against the component — a wrong default, + value range, precedence/fallback behavior, version-support statement, deprecation, or DOM + description. Verify against the typed source / official API (and official framework docs for + version behavior); if unverifiable, don't assert it. +- D10 (Warning) **Voice/tone drift** — prose isn't imperative/second-person present tense, mixes + first-person-plural narration ("we create") with how-to, or carries filler ("simply", "just") or + marketing inside instructional prose. +- D11 (Error) **Blanket or unverified accessibility-conformance claim** — "fully accessible" / + "WCAG compliant" prose, a conformance target (WCAG level, Section 508, EN 301 549) with no official + source, a conformance-table row not traceable to behavior verified on the page or in source, an + "N/A" filler row for an irrelevant criterion, or an invented testing/AT matrix or VPAT link. + Fix: criterion-level rows tied to observable behavior, or `‹VERIFY:…›`. + +### E. Samples & links +- E1 (Warning) `` missing an `alt`. +- E2 (Suggestion) Near-duplicate samples that teach the same task. +- E3 (Warning) Hand-written API URL instead of ``. +- E4 (Warning) `
` or `` placed directly before or after a ``, code fence, + or table (dividers separate prose only). +- E5 (Warning) A `` sets both `fitContent` and `height` — they are mutually exclusive. + `fitContent` sizes the iframe to the component, so remove `height`. +- E6 (Error) An `` whose `type` has no generated reference page — typically an abstract/base + class (e.g. `ButtonBase`): the link renders (e.g. `IgrButtonBase`) but points nowhere. Verify the + `type` appears as an `` target elsewhere in the doc set; link base-class members through + the concrete component (`type="Button" member="href"`) instead. + +### F. Formatting & altitude +- F1 (Suggestion) A `ul`/`ol` with a single item that should be a paragraph. +- F2 (Warning) A deprecated/legacy setup (e.g. NgModule) shown **above** the current recommended + approach (standalone) — reorder so current is first, legacy after and marked as such. +- F3 (Suggestion) The **Styling** section doesn't open with a `` of the styled result, or its + first subsection isn't `### Sass Theming`. +- F4 (Suggestion) **Getting Started** repeats the generic install boilerplate (the `ng add` command + with the "install the library first / read getting started" prose that is identical on every page) + instead of compressing it to a **one-line prerequisite link** and leading with the component-specific + import. +- F5 (Warning) An inline Properties/Styling-Variables table has rows not verified from source, or is + presented as generated when the repo has no generator (curated + `` is the current rule). +- F6 (Warning) A version-migration note lives inside a code-fence comment, or legacy/alternative setup + (e.g. NgModule) is scattered outside **Troubleshooting** → move it into Troubleshooting as + question → cause → fix; keep Getting Started and samples on the current path only. +- F7 (Warning) An **inline** fenced code snippet uses a deprecated API or outdated framework idiom + (e.g. `standalone: true`, `*ngIf`/`*ngFor`, an old import path) → modernize it. Scope is authored + snippets only; **live `` embeds are out of scope** (fix those in the sample project), and + legacy snippets deliberately kept in **Troubleshooting** are exempt. +- F8 (Warning) The Styling section has **per-theme variable tables** (the legacy + `.theme-switcher-wrapper` / `.theme-table` tabbed markup) or a **default-value column** in the + Styling Variables table. Every theme extends the same base schema — the variable *set* is identical + across themes, only the default values differ — so per-theme tabs document a difference that doesn't + exist, and defaults are per-theme data for the generated API reference. Fix: collapse to **one + two-column table (variable · what it changes)**. + +## Report format + +Produce this exact shape: + +``` +# Audit: ( · ) + +**Verdict:** +**Summary:** <2–3 sentences: biggest issues and the through-line.> + +## Findings +### · · +- **Where:**
+- **Issue:** +- **Principle:** +- **Fix:** + + + +## Quick wins + +``` + +Keep every **Fix** concrete and applyable — the corrected heading text, the exact sentence to move and +where, the table columns to add. Group findings by severity, most severe first. If the topic is clean, +say so plainly and note what it does well rather than inventing problems. diff --git a/.claude/skills/igniteui-doc-topics/references/diataxis-cheatsheet.md b/.claude/skills/igniteui-doc-topics/references/diataxis-cheatsheet.md new file mode 100644 index 0000000000..2ef9bceeac --- /dev/null +++ b/.claude/skills/igniteui-doc-topics/references/diataxis-cheatsheet.md @@ -0,0 +1,72 @@ +# Diátaxis cheat-sheet + +Condensed from https://diataxis.fr (tutorials, how-to, reference, explanation, compass). +This is the *reasoning layer*. For how the four modes attach to Ignite UI sections, see +`house-style.md`. Read this whenever you're unsure what kind of content a topic — or a single +section — should be. + +## The compass (use this first, every time) + +Two questions decide the mode. Ask them of the *content in front of you* or the *user need*: + +| If the content… | …and serves the user's… | …then it is… | +| ----------------- | ----------------------- | ------------ | +| informs **action** | **acquisition** of skill (study) | a **tutorial** | +| informs **action** | **application** of skill (work) | a **how-to guide** | +| informs **cognition** | **application** of skill (work) | **reference** | +| informs **cognition** | **acquisition** of skill (study) | **explanation** | + +- *action* = doing, practical steps. *cognition* = thinking, propositional knowledge. +- *acquisition* = study/learning. *application* = getting real work done. + +Apply the compass at any zoom level: a whole topic, a section, even a sentence. When a section +"feels off," run the compass on it — usually it has drifted into a second mode. + +## The four modes at a glance + +| Mode | Serves | Question it answers | Cardinal rule | Voice | +|------|--------|---------------------|---------------|-------| +| **Tutorial** | learning by doing | "Teach me, hold my hand" | Ruthlessly minimise explanation; guarantee success | "In this tutorial *we* will…" | +| **How-to guide** | a competent user's task | "Help me get X done" | Action only; no teaching, no digression | "To achieve X, do Y." | +| **Reference** | look-up during work | "What exactly is X / its options?" | Describe and *only* describe; be austere | "The `value` property accepts a number 0–5." | +| **Explanation** | understanding a topic | "Tell me about X / why?" | Discuss, connect, weigh alternatives; stay bounded | "X exists because… An alternative is…" | + +### Tutorial — learning-oriented +A lesson. The learner learns *by doing*, under guidance, toward a meaningful, guaranteed-to-succeed +result. Show where they'll end up; deliver visible results early and often; keep a narrative of the +expected ("after a moment you'll see…"); ignore options and alternatives; minimise explanation (link +out instead). Reliability is sacred — it must work for every reader, every time. + +### How-to guide — task/goal-oriented +Directions that guide an already-competent user through a real-world problem. Defined by the *user's +goal*, not by the machinery ("How to validate a reactive form," not "The validation API"). A sequence +with flow. Omit the unnecessary; usability beats completeness. Title says exactly what it shows +("How to…"). This is a recipe, not a cooking lesson. + +### Reference — information-oriented +Neutral, authoritative technical description of the machinery — properties, methods, events, options. +Structured to mirror the code. Austere: you *consult* it, you don't read it. No instruction, no +opinion, no explanation — link out for those. Tables and examples are ideal. Best when +auto-generated from the typed source so it never drifts. + +### Explanation — understanding-oriented +Discursive treatment of a topic that permits reflection. Higher, wider view than the other three. +Answers "Can you tell me about…?" and "Why…?". Make connections, give context and history, weigh +alternatives and admit opinion. Name it with an implicit *"About …"* in front of the title. Keep it +bounded — it tends to absorb instruction and reference that belong elsewhere. + +## The two classic confusions (where writers go wrong) + +1. **Tutorial vs how-to.** Same steps, different need. A tutorial *teaches* a beginner (success + guaranteed, no choices, minimal why). A how-to serves a competent user getting a *specific job* + done (adaptable, may fork, assumes background). Don't merge them. +2. **Reference vs explanation.** Reference *describes* (cognition + work): austere, neutral, complete. + Explanation *illuminates* (cognition + study): discursive, contextual, opinionated. A properties + table is reference; "why the component works this way" is explanation. Keep them in separate + sections and link between them. + +## The golden rule + +Each unit of documentation should serve **one** need in **one** mode. When two modes want to live in +the same section, split them and cross-link. In Ignite UI topics this happens at the *section* level — +see the composite-topic principle in `SKILL.md`. diff --git a/.claude/skills/igniteui-doc-topics/references/house-style.md b/.claude/skills/igniteui-doc-topics/references/house-style.md new file mode 100644 index 0000000000..484cd57735 --- /dev/null +++ b/.claude/skills/igniteui-doc-topics/references/house-style.md @@ -0,0 +1,329 @@ +# Ignite UI house style + +The Ignite UI documentation conventions an authored or audited topic must follow. Pair this with +`diataxis-cheatsheet.md` (the *why*) and the section→mode map in `SKILL.md`. + +> **Current vs target state.** The live `vnext` repo is *pre-standardization* — many topics use +> drifted headings (e.g. `## Angular Rating Example`, `## Configuration`). This file describes the +> **target** standard (revision-2 blueprint). When **authoring**, write to the target. When +> **auditing**, measure against the target and report the gap. + +## Two doc sets + +| Doc set | Frameworks | Path (vnext) | Layout | One topic = | +|---|---|---|---|---| +| **Angular** | Angular only | `docs/angular/src/content/en/components/` | flat `*.mdx` | one framework | +| **xplat** | React · Web Components · Blazor | `docs/xplat/src/content/en/components//` | categorized `*.mdx` | **one file, all three frameworks** | + +The **same section list, order, and names apply to both sets.** Differences are mechanical only (see +Per-framework mechanics), never the shape of the page. **Dependencies** appears in both sets — it +covers modules to import (Angular) or supporting components/themes required to render or function +(xplat); currently seen as `## Theming Dependencies`. + +## File format & frontmatter + +Topics are **Astro `.mdx`**. Frontmatter is YAML. Observed + target fields: + +```yaml +--- +title: "Angular Star Rating Component – Ignite UI for Angular - MIT license" # SEO title +description: "…" # <=~160 chars, shaped as an answer ("X is a … that …") +keywords: "…" # comma-separated +license: MIT +mentionedTypes: ["Rating"] # xplat: API types referenced on the page +llms: + description: "…" # AI-facing one-liner; the exact text an assistant uses to summarize +relatedComponents: [Toast, Banner] # TARGET field — drives the When to Use trigger (see below) +--- +``` + +- **`llms.description`** already exists in both sets and is high-value — write it as a crisp, + self-contained answer sentence. It is *not* optional filler. +- **`relatedComponents`** is the revision-2 trigger and is **not yet in the repo**. When authoring to + target, set it. When auditing, treat a missing-but-warranted value as a finding, and a set value + with no **When to Use** section as a hard error. + +### MDX imports (declare what you use) + +```mdx +import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; +import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; +import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; # xplat only +``` + +## Per-framework mechanics + +- **Prefixes differ by framework/library — don't assume one for all:** + - **Angular** → native **`igniteui-angular`**, **`igx-`** tags / **`Igx…Component`** classes. The + Angular doc set documents this library. + - **Web Components** → **`igniteui-webcomponents`**, **`igc-`** tags / **`Igc…Component`** classes. + - **React** → **`igniteui-react`**, a **wrapper around the `igc`** web components. + - **Blazor** → **`igniteui-blazor`**, a **wrapper around the `igc`** web components. +- **Net effect:** the **xplat doc set (React / WC / Blazor) is entirely `igc`-based** — WC is `igc` + directly; React and Blazor wrap it. The **Angular doc set is `igx`**. +- **Exception — WC-first components in the Angular docs.** Some newer components are built as web + components and surfaced in the Angular docs via the `igc` element rather than a native `igx` one + (verified: the Angular **Rating** topic installs `igniteui-webcomponents`, registers + `IgcRatingComponent`, and renders ``). So **don't assume `igx` for every Angular topic** — + verify the tag/class per component. +- **Angular set:** plain prose, no platform tokens. Registers and renders whichever the component is + (`igx-…` native, or the `igc-…` WC for the exceptions above). +- **xplat set:** the *same file* serves React / WC / Blazor via: + - **Tokens** the build resolves: `{Platform}`, `{ProductName}`, `{PackageWebComponents}`, + `{PackageReact}`, `{PackageBlazor}`, etc. Use them in title/description/keywords/headings and prose + — never hard-code "React" where a token belongs. + - **`…`** to wrap framework-specific content + (install commands, imports, snippets). `for` values: `WebComponents`, `React`, `Blazor`. +- **Live samples** embed the same way in both sets: + `` +- **API links** use `` rather than hand-written URLs so they resolve per framework. + +## Never fabricate API identifiers (zero-risk rule) + +The skill's job is structure and prose, **not** to invent the API surface. Do **not** emit a guessed +tag, class, package name, property, method, event, CSS part, or theming variable. A plausible-but-wrong +name that a reader copies is worse than an obvious gap. + +- Use an identifier **only** when it is verified — from the component's typed API source, an existing + topic, or the user. The naming patterns are known (Angular `igx-` / `IgxComponent`; WC and + its React/Blazor wrappers `igc-` / `IgcComponent`), but the pattern is not a licence to + guess — confirm the exact prefix *and* `` per component (some Angular topics are `igc` — see the + exception above). +- When you must reference an unverified identifier, write a visible placeholder instead of a guess: + `‹VERIFY: exact export name›`. For a table, emit the fixed column headers and a single injection note + — invent no rows. +- This applies equally to React/Blazor wrapper symbols: they resolve to the `igc` core, so prefer the + verified `igc` usage and mark any wrapper-specific class you can't confirm with `‹VERIFY:…›`. +- **`` targets are identifiers too.** A `type` that exists in the source is not enough — it + must have a generated reference page, and the only reliable check is an existing `` with that + `type` elsewhere in the doc set. Abstract/base classes in particular (e.g. `ButtonBase`) may appear in + `mentionedTypes` yet have no page — the rendered link (e.g. `IgrButtonBase`) points nowhere. Link base-class + members through the concrete component instead (`type="Button" member="href"`), and list only the concrete + component under **API References**. + +## Component topic — canonical section order + +Required = every component topic, always this order. Conditional = only when relevant, but always in +this slot. **These names are the only allowed H2s.** Anything feature-specific becomes a sub-heading +under **Usage**, never a new top-level section. + +| # | Section (`##`) | Required? | Diátaxis mode | Contents | +|---|---|---|---|---| +| 1 | *Title + one-line definition* (`#` + lead ¶) | required | orient / reference | H1 is **`‹Component› Component`** — **no** framework prefix, **no** "Overview" suffix (the framework lives in the SEO `title`). Follow with one plain sentence: what it is, what problem it solves. Mirror `llms.description`. | +| 2 | **Overview** | required | **explanation** | Introduces the component: its primary purpose, when to reach for it, and the problems it solves, in two sub-headings — **When to Use** and **When Not to Use** (when `relatedComponents` is non-empty, name the better-fit sibling by name and link it; otherwise state the boundary generically). No install steps or API detail here. | +| 3 | *Live Demo* | required | demonstration (action) | `` of the simplest useful state, **before** any further prose. | +| 4 | **Anatomy** | conditional (recommended) | orientation (reference) | Opens with a screenshot/GIF of the component's parts or the behavior being shown, then the **DOM tree / skeleton** (rendered elements, parts, slots). If the visual asset doesn't exist yet, leave a `{/* TODO */}` marker rather than a broken image. | +| 5 | **Getting Started** | required | how-to | **Lead with the component-specific import/registration** — the page-unique, high-value part. Compress the generic library install to a **single prerequisite line linking the general getting-started topic** (an inline `ng add igniteui-angular` as a parenthetical is fine); **don't** repeat the multi-sentence install boilerplate that is identical on every component page. Show the **current** registration (standalone import) first; put legacy NgModule **after**, marked as legacy. | +| 6 | **Usage** | required | how-to | Smallest working snippet per common task; feature specifics are sub-headings here. Sub-headings name the **feature, not the component** (`Shape`, not `Avatar Shape`). Cover **every** public input; state behavioral relationships once (e.g. content-type priority) instead of repeating per option. Styling content belongs in **Styling**, not here. | +| 7 | **Best Practices** | required | **explanation** | Practical design recommendations, illustrated with correct-vs-incorrect usage (do/don't pairs). Promotes consistency, usability, and accessibility, and calls out common mistakes. Guidance and examples only — no install steps, no property tables, no accessibility-conformance detail (those stay in their own sections). | +| 8 | **Properties** | required | reference | Table: name · type · default · description. (Replaces "Configuration".) | +| 9 | **Methods** | conditional | reference | Table of callable actions. | +| 10 | **Events** | conditional | reference | Table of emitted events. | +| 11 | **Styling** | required when applicable | how-to + reference | **Open with a `` of the styled result** + one intro line, then the **Styling Variables table** (**one table** — variable · what it changes; **no default-value column, no per-theme tabs**) and styleable-parts table. Subsections cover each approach — **first `### Sass Theming`** (the primary Sass theme workflow), then others (e.g. `### Tailwind`, `### Custom sizing`). All styling content lives here, not under Usage. | +| 12 | **Accessibility** | required | reference | Three sub-sections, in order: **Keyboard Interaction** (key→action table), **Screen Readers / ARIA**, **Accessibility Compliance** (conformance evidence — see the sub-structure spec below). | +| 13 | **Troubleshooting** | conditional (required when version-migration or legacy-setup notes exist) | how-to | Gotchas phrased as the reader's real question; answer as cause → fix. **Collect version-migration notes, deprecations, and legacy/alternative approaches here** — not buried in code-fence comments or scattered asides. | +| 14 | **API References** | required | reference | `` out to the full generated reference; don't duplicate it. | +| 15 | **Dependencies** | conditional | reference | Themes, styles, or supporting components the component relies on to render or function — modules to import (Angular) or supporting components/themes (xplat). (Currently "Theming Dependencies".) | +| 16 | **Additional Resources** | required | navigation | Forums, GitHub, related topics. | + +**When Not to Use trigger:** every component topic carries **Overview** with its **When to Use / When +Not to Use** sub-headings. When `relatedComponents` is non-empty, **When Not to Use** must name the +specific better-fit sibling(s) by name and link them; when it's empty (standalone primitives like +Badge/Divider), **When Not to Use** states the boundary without inventing a sibling. (The H2 section +named **Overview** is distinct from the banned "Overview" *suffix* on the H1 title — keep the section, +drop the suffix.) + +**Reference-table contract:** Properties / Methods / Events tables are **generated from the same typed +API source** as the full reference — not hand-typed. Inline tables = the core knobs for fast scanning; +**API References** links to the complete set. One source, so nothing drifts. **When authoring, do not +hand-write or invent rows:** emit the fixed column headers (`name · type · default · description`) and a +single build-injection note, and leave the row values to the generator. Inventing a plausible property +or event name is exactly the failure this contract exists to prevent. + +**Live-sample contract:** exactly one top preview; add Usage samples only for distinct, user-facing +tasks (selection, editing, sorting, validation, templating, styling). Soft max **10 samples/page**; +up to 10 is fine, and only clear sprawl past that warrants splitting into focused topics. + +### `` configuration — pick the props deliberately + +`` renders a live demo (iframe + source-code tabs + live-edit buttons). **`src` is required and must +point at a real demo path** — treat it like any other identifier under the zero-risk rule: never invent or +guess a `src`, an `lob`/`dv`/`crm` base, or a path; use one only when it's verified from the sample project +or an existing topic, else leave a `‹VERIFY: demo path›` marker. Never hand-edit the demo's code — that lives +in the separate sample project. + +Choose the display config from **what the sample is showing**, not by habit: + +| Prop | Default | Use it when… | +|---|---|---| +| `src` | — (required) | Always. Relative demo path. | +| `alt` | — | **Always** — the iframe title for accessibility. A missing `alt` is an audit finding (E1). Describe the demo, e.g. `alt="Angular Calendar range selection"`. | +| `height` | `400` | The demo's natural height isn't ~400px. Match the content. **Mutually exclusive with `fitContent`** — set one or the other, never both. | +| `fitContent` | off | The component is small or variable-height (badge, chip, avatar, icon, switch), **or a compact standalone sub-view** (e.g. a calendar days/months/years view), and a fixed frame would waste or clip space. The iframe grows to the component's own height, so **do not also set `height`** — drop it entirely. Ignores `resizable`. | +| `iframeOnly` | off | The **result** is the point and the source isn't instructive — purely visual demos, or a Styling preview whose styling is applied upstream (not in copyable code). Drops the code tabs/footer. Keep the tabs when the code *is* the lesson (e.g. a Sass `calendar-theme` snippet). | +| `fullscreenBtn` | off | Paired with `iframeOnly` for large/complex visual demos that benefit from full-screen. | +| `resizable` | off | Responsiveness is the lesson (grids, layout, splitter, dock manager) — lets the reader drag the width. Ignored with `fitContent`. | +| `position` | — | A small component would otherwise sit in the top-left; align it (`center`, etc.). | +| `spacing` | — | The demo needs breathing room around the iframe (`sm`/`md`/`lg` = 8/16/32px). | +| `noBorder` | off | The default border competes with the demo visually. Cosmetic — use sparingly. | +| `lob` / `dv` / `crm` | default base | The demo lives in the LOB, Data-Viz, or CRM demos app rather than the default — **verify before setting**. | + +Defaults are right for most Usage samples: ``. Reach for the extra props +only when the component type calls for it — the top preview and standard task demos keep the code tabs (no +`iframeOnly`); the **Styling** section still opens with a styled-result ``, using `iframeOnly` only +when its styling isn't shown as copyable code. + +### Accessibility — required sub-structure + +`## Accessibility` always carries three `###` sub-sections, in this order. All three are **reference** +mode: statements of fact in tables and short lists — no steps, no marketing. + +1. **`### Keyboard Interaction`** — one key → action table, verified against the component's key + handlers. Note how the component is reached (Tab) and any condition that removes it from the tab + order. +2. **`### Screen Readers / ARIA`** — the roles, `aria-*` attributes, and announcements the component + provides (from source), plus what the reader must supply (e.g. `aria-label` when the visible + content doesn't describe the action). +3. **`### Accessibility Compliance`** — the conformance evidence, in this shape: + - **Lead sentence** naming the conformance target (WCAG version + level; Section 508 / EN 301 549 + where applicable). This is a product-level claim — state it only from an official Infragistics + statement; otherwise write `‹VERIFY: conformance target›`. + - **Conformance table** — two columns: **Criterion · How the component complies**. List only the + WCAG success criteria *relevant to this component*, each row grounded in behavior already + verified on this page (the keyboard table, the ARIA facts, the typed source). Link each + criterion to its WCAG Understanding page. Common criteria to pick from: + 1.3.1 Info and Relationships (roles/structure) · 1.4.1 Use of Color (states not conveyed by + color alone) · 1.4.3 Contrast (Minimum) (default themes) · 1.4.11 Non-text Contrast · + 2.1.1 Keyboard + 2.1.2 No Keyboard Trap (full keyboard operability) · 2.4.3 Focus Order · + 2.4.7 Focus Visible (focus ring) · 2.5.7 Dragging Movements (every drag interaction needs a + keyboard/single-pointer alternative — splitter, slider, dock manager) · 2.5.8 Target Size + (Minimum) · 4.1.2 Name, Role, Value · 4.1.3 Status Messages (components that announce — toast, + snackbar, progress). Omit irrelevant criteria entirely — no "N/A" filler rows. + - **Your responsibilities** — a short list of what the app author must still do for the page to + conform: provide the accessible name, keep sufficient contrast when overriding themes, preserve + a logical focus order in the surrounding layout, keep minimum target sizes when custom-sizing. + Cross-link the Usage/Styling sections that show *how* — don't repeat the steps here. This split + (what the component guarantees vs what the reader owes) is the highest-value content of the + sub-section for both humans and AI assistants. + - **Known exceptions** *(only when real)* — criteria the component doesn't fully meet, each with + its workaround or tracking link. An honest, specific gap beats a silent one. + - **Validation & resources** *(optional, verified only)* — the screen reader / AT combinations the + component is tested with, and links to the product accessibility statement / VPAT and the + matching [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/) pattern. + Omit when unverified — never invent a testing matrix. + + Compliance claims are the highest-risk statements on the page — they carry legal weight, and a + wrong one is copied into the reader's own conformance report. The zero-risk rule applies at full + strength: no blanket "fully accessible" / "WCAG compliant" sentence, ever; every table row traces + to observable, verified behavior; product-level claims come only from an official source. + +## Overview topics + +**5a. Concept / guide overview** (Diátaxis: *explanation*) — e.g. "Theming concepts": +Title + intro → **What You'll Learn** (roadmap) → Concept sections → *Key Capabilities* (cond.) → +*When to Use / When Not to Use* (cond.) → **Next Steps** → **API References / Additional Resources**. + +**5b. Category / index overview** (Diátaxis: *reference/navigation* — a map) — e.g. "Charts overview": +Title + intro → **Types / Members** (identical micro-structure per entry: one-line def + link + small +``) → *Key Features* (cond.) → **Next Steps / API References / Additional Resources**. + +Guardrails: cap each section at ~3 short paragraphs (else add sub-sections); isolate marketing copy in +a single "Why {ProductName}" section — never thread it through instructional content. + +## Naming reconciliation (drift → standard) + +| Seen in the wild | Standard name | +|---|---| +| "Angular X Component Overview"; "X Component Overview"; "{Platform} X Component Overview" (H1) | **`X Component`** (H1 — drop framework + "Overview") | +| Setup; "Getting Started with…"; "Getting Started with Ignite UI for Angular X" | **Getting Started** | +| Code Snippet; Examples; "Using the … Component"; "{Platform} X Example"; "Angular X Example" | **Usage** | +| "Avatar Shape"; "‹Component› ‹Feature›" (Usage sub-heading) | **`‹Feature›`** (drop the component name) | +| Configuration | **Properties** | +| "X vs Y"; "Choosing Between X and Y"; Behavior; Feature Integration | **When to Use** (as `###` under **Overview**) | +| top-level `## When to Use` / `## When Not to Use`; **When to Use / When Not to Use nested under `## Anatomy`** | **`### When to Use` / `### When Not to Use`** nested under **`## Overview`** (first section, before Live Demo) | +| Summary (as lead-in) | intro ¶ or **What You'll Learn** | +| Keyboard Navigation | **Accessibility** | +| WAI-ARIA Support; Compliance; Section 508; Accessibility Statement | **`### Accessibility Compliance`** (under **Accessibility**) | +| Do's and Don'ts; Guidelines; Recommendations | **Best Practices** | +| Theming (H2) | **Styling** (H2); the Sass approach becomes `### Sass Theming` under it | +| Known Limitations; Known Issues and Limitations; Limitations | **Troubleshooting** | +| API; API Reference (singular) | **API References** | +| Theming Dependencies | **Dependencies** | + +## Write-for-both-audiences rules (people + AI assistants) + +1. **One job per section** — self-contained; no "as mentioned above." A section must make sense landed-on cold. +2. **Lead each section with one plain, specific sentence** before any table/code — skip empty boilerplate. +3. **Use the standard section names everywhere** — "Accessibility" always means the same thing. +4. **Phrase guidance/troubleshooting as real questions** — When-Not-to-Use is the highest-value content for answer accuracy; name the sibling explicitly. +5. **Reference lives in tables**, generated from the typed source. +6. **Strong `description` / `llms.description`** — <~160 chars, answer-shaped. +7. **Document theming variables** — variable · what it changes, in **one table for all themes**. No default-value column: defaults are per-theme values that live in the generated API reference, not the topic. + +## Formatting & altitude + +- **No divider hugging a block.** Never place `
` or `` directly before or after a + ``, code fence, or table — those blocks carry their own separation. Dividers separate + *prose* sections only; in practice a topic rarely needs them at all. +- **Single item ⇒ paragraph.** A `ul`/`ol` with one item is a paragraph. Use a list only for two or + more parallel items. +- **Current API first, legacy after.** Show the current/recommended approach first (e.g. the + standalone component import); place deprecated/legacy approaches (NgModule) *below* it, explicitly + marked as legacy — never above the current one. +- **Don't repeat the generic install boilerplate.** The `ng add igniteui-angular` + "read the getting + started topic" prose is identical on every component page — collapse it to a **one-line prerequisite + link** and lead Getting Started with the component-specific import instead. This mirrors how the major + component libraries (Angular Material, MUI, Ant Design, PrimeNG) work: install lives in one central + page; each component page shows only its own import. Keep the prerequisite as a single linked line + (optionally with an inline `ng add` token) so a cold-landing reader or AI still has the pointer — just + not the repeated paragraph. +- **Styling leads with the result.** The Styling section opens with a `` of the styled + outcome, then the tables; its first subsection is `### Sass Theming` (the Sass theme workflow), then + the other approaches (`### Tailwind`, `### Custom sizing`, …). +- **One styling table — never per-theme tabs, never default values.** In the `theming` repo every + theme schema `extend`s the same base schema and only overrides *values* (e.g. `$material-switch`, + `$fluent-switch`, `$indigo-switch` all extend `$light-switch`; `$bootstrap-switch` extends + `$fluent-switch`), so **every theme exposes the identical variable set** — only the defaults differ. + Per-theme tabbed tables (the legacy `.theme-switcher-wrapper` / `.theme-table` markup) therefore + document a difference that doesn't exist; replace them with **one two-column table: + variable · what it changes**. Don't add a defaults column either — defaults vary per theme and + belong to the generated API reference, and the durable content is the variable's name and effect. +- **Audit & modernize inline code snippets — not the samples.** Fenced code blocks (` ```… ``` + `) are authored in the topic, so verify and update them: no deprecated APIs or outdated framework + idioms (drop `standalone: true`; prefer Angular's built-in control flow `@if`/`@for` over + `*ngIf`/`*ngFor`; use verified imports, selectors, and tags). The live **``** embeds render + from the separate sample project — **never hand-edit their code**; fix those upstream. The only + intentionally "old" snippets are the legacy ones quarantined in **Troubleshooting**. +- **Omit `standalone: true` (Angular).** Components are standalone by default since Angular v19 + (igniteui-angular targets far newer), so it's redundant in examples — don't write it. Show + `standalone: false` only when illustrating the legacy NgModule path (in Troubleshooting). +- **Version & legacy notes live in Troubleshooting.** Don't bury "prior to vX use…" migration notes + in code-fence comments, and don't scatter legacy/alternative setup (e.g. NgModule) across the page. + Collect them in **Troubleshooting**, each phrased as question → cause → fix. Getting Started and + code samples show only the current, recommended path. +- **Curated (not generated) reference tables — for now.** No build-time generator injects inline + Properties/Styling-Variables tables yet (only the full API reference is generated, reached via + ``). Until one exists, hand-author a **small core** table whose every row is **verified + from source** (typed component for props; the `@param` doc-comments in the component's + `_…-theme.scss` for styling vars) and link `` for the complete set. The zero-risk rule + still applies: no unverified rows. + +## Voice & tone + +Write instructions the same way across every topic so readers (and assistants) get one predictable voice. + +- **Imperative, second person, present tense.** "Set the `shape` attribute…", "Import the component…" — not "we create…" or "the developer should…". Address the reader as *you* only when needed for clarity. +- **One voice per topic.** Don't mix imperative how-to with first-person-plural narration ("we create") or tutorial hand-holding. Reference sections (Properties/Styling tables, Accessibility) stay descriptive. +- **Specific over vague; cut filler.** Name the exact attribute, value, or behavior. Drop "simply", "just", "in order to", "as you can see", and empty lead-ins. +- **No marketing in instructional prose.** Keep promotion out of how-to/reference; overview topics isolate it in a single "Why {ProductName}" slot. +- **Name features by their real Ignite UI identifier** (e.g. `igx-icon`, not "material icon") and cross-link the topic. + +## Verify every claim against the component + +The zero-risk rule is not limited to identifiers — **every statement of fact must be verified against the actual component before it ships or is recommended as an edit.** This includes defaults, value ranges, precedence/fallback behavior, version support ("since vX"), deprecations, emitted events, and rendered DOM. + +- **Source of truth, in order:** the component's typed source (inputs, `@HostBinding`, template, theme `.scss` `@param` comments) → the official generated API docs → an existing verified topic → the user. For framework-version behavior (e.g. Angular standalone defaults), check the **official framework docs**, not memory. +- **When recommending edits, verify first.** Never "correct" prose into a plausible-sounding claim you haven't checked — a confident wrong statement is worse than the original. +- **If you can't verify it, don't assert it.** Write `‹VERIFY: …›` or leave the existing text and flag it — never guess a default, a version, or a behavior. +- Behavioral claims that read fine but contradict the source (e.g. "the image falls back to initials on load error" when the code only sets precedence) are exactly what this rule catches. From aa578b86c838948431bde5e0ff55d6f81d031aff Mon Sep 17 00:00:00 2001 From: desig9stein Date: Thu, 9 Jul 2026 11:36:48 +0300 Subject: [PATCH 2/7] fix(docs): Update Angular Avatar,calendar documentation using the new skill. --- .../src/content/en/components/avatar.mdx | 306 ++++--- .../src/content/en/components/calendar.mdx | 819 ++++++++---------- 2 files changed, 552 insertions(+), 573 deletions(-) diff --git a/docs/angular/src/content/en/components/avatar.mdx b/docs/angular/src/content/en/components/avatar.mdx index ed90d5299c..f2921cde8f 100644 --- a/docs/angular/src/content/en/components/avatar.mdx +++ b/docs/angular/src/content/en/components/avatar.mdx @@ -1,215 +1,214 @@ --- title: Angular Avatar Component – Ignite UI for Angular | Infragistics | MIT license -description: Ignite UI for Angular Avatar control enables users to add images, material icons or initials within any application for instances such as a profile button. +description: The Ignite UI for Angular Avatar is a compact UI element that represents a user or entity with a profile image, an igx-icon, or their initials. keywords: Angular Avatar component, Angular Avatar control, Ignite UI for Angular, Angular UI components license: MIT llms: - description: "Angular Avatar component helps adding initials, images, or material icons to your application." + description: "The Angular Avatar is a compact UI element that represents a user, entity, or object by displaying their profile image, an igx-icon, or their initials." +relatedComponents: [Badge] --- import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# Angular Avatar Component Overview +# Avatar Component
-Angular Avatar component helps adding initials, images, or material icons to your application. +The Angular Avatar is a compact UI element that represents a user, entity, or object by displaying their profile image, an `igx-icon`, or their initials.
- -## Angular Avatar Example +## Overview - +### When to Use -
+Use the avatar to represent a user, entity, or object with a compact image, icon, or set of initials — for example a profile button, a comment author, or a list item's leading visual. -## Getting Started with Ignite UI for Angular Avatar +### When Not to Use -To get started with the Ignite UI for Angular Avatar component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: +To display a count, status, or notification indicator rather than represent an entity, use the component, which is designed to decorate other elements (including avatars) with a small count or status icon. -```cmd -ng add igniteui-angular -``` + -For a complete introduction to the Ignite UI for Angular, read the [_getting started_](/general/getting-started) topic. +## Anatomy -The next step is to import the `IgxAvatarModule` in your **app.module.ts** file. +{/* TODO: add an anatomy diagram (screenshot or GIF) labeling the avatar's parts. */} -```typescript -// app.module.ts +The avatar is a single host element that renders one content template, chosen by [content priority](#content). Its rendered DOM is: -... -import { IgxAvatarModule } from 'igniteui-angular/avatar'; -// import { IgxAvatarModule } from '@infragistics/igniteui-angular'; for licensed package - -@NgModule({ - ... - imports: [..., IgxAvatarModule], - ... -}) -export class AppModule {} +``` +igx-avatar[role="img"] // host — shape & size set via attributes / CSS vars +└─ one of, by priority: + ├─ div.igx-avatar__image // `src` set — image painted as a background + ├─ igx-icon // `icon` set + ├─ span // `initials` set — first two characters + └─ // custom projected content ``` -Alternatively, as of `16.0.0` you can import the `IgxAvatarComponent` as a standalone dependency. +## Getting Started + +Install Ignite UI for Angular first (`ng add igniteui-angular`) — see [Getting Started](/general/getting-started) for the full walkthrough. + +Import the standalone `IgxAvatarComponent` and add it to your component's `imports` array, then use the `` tag in that component's template. ```typescript // home.component.ts - -... +import { Component } from '@angular/core'; import { IgxAvatarComponent } from 'igniteui-angular/avatar'; -// import { IgxAvatarComponent } from '@infragistics/igniteui-angular'; for licensed package +// Licensed package: import from '@infragistics/igniteui-angular' instead @Component({ selector: 'app-home', - template: '', - styleUrls: ['home.component.scss'], - standalone: true, - imports: [IgxAvatarComponent] + imports: [IgxAvatarComponent], // makes available in this template + template: '' }) export class HomeComponent {} ``` -Now that you have the Ignite UI for Angular Avatar module or component imported, you can start with a basic configuration of the `igx-avatar` component. - -## Using the Angular Avatar Component +## Usage -The Ignite UI for Angular Avatar component comes in three shapes (square, rounded, and circle) and three size options (small, medium, and large). It can be used for displaying initials, images or icons. +The avatar renders initials, an image, or an [`igx-icon`](/icon), in one of three shapes and three preset sizes. -### Avatar Shape +### Shape -We can change the avatar shape through the `shape` attribute setting its value to `square`, `rounded` or `circle`. By default, the shape of the avatar is `square`. +Set the `shape` attribute to `square`, `rounded`, or `circle`. The default is `square`. ```html ``` -### Avatar displaying initials +### Size -To get a simple avatar with (i.e. JS for 'Jack Sock'), add the following code inside the component template: +Set the `size` attribute to a preset value — `small`, `medium`, or `large` (default `small`). For arbitrary sizes, use the CSS variables described under [Custom sizing](#custom-sizing). ```html - + ``` -Let's enhance our avatar by making it circular and bigger in size. +### Content -```html - -``` +An avatar displays a single kind of content, chosen by **priority**: (image) wins over , which wins over . Set the one you need — a higher-priority value hides the others (this is a precedence rule, not an image load-failure fallback). If none is set, the avatar renders its projected content. -We can also change the background using the `--ig-avatar-background` CSS variable or set a color on the initials through the `color` property. - -```scss -// avatar.component.scss - -igx-avatar { - --ig-avatar-background: #e41c77; - color: #000000; -} +**Initials** — the first two characters of `initials` are shown (e.g. `JS` for "Jack Sock"): +```html + ``` - -The `roundShape` property of the `igx-avatar` component have been deprecated. The `shape` attribute should be used instead. - + -If all went well, you should see something like the following in the browser: +**Image** — set the image URL via `src`: - +```html + +``` -### Avatar displaying image + -To get an avatar that displays an image, all you have to do is set the image source via the `src` property. +**Icon** — render an [`igx-icon`](/icon) by setting its name via `icon`: ```html - - + ``` + +The avatar renders icons with the [`igx-icon`](/icon) component. To use Google's Material Icons font, add the following to your `index.html`: `` + -If all went well, you should see something like the following in the browser: + - +## Best Practices -### Avatar displaying icon +- Pick one content strategy per context and use it consistently — mixing images, icons, and initials in the same list of avatars reads as inconsistent. +- Set only the content you intend to show. `src`, `icon`, and `initials` follow a fixed precedence rather than falling back automatically on failure, so an unreachable image URL won't be replaced by initials — verify the URL if you need a reliable result. +- Set a descriptive `aria-label` whenever the avatar identifies a specific person or entity, not just when it's convenient. +- Don't use the avatar to show a count, status, or notification badge — decorate it with instead of encoding that information into the initials or icon. -Analogically, the avatar can display an icon via the property. Currently all icons from the material icon set are supported. +## Properties -```html - - -``` +The core inputs used to configure the avatar are listed below. For the complete, always-current API surface, see the [API References](#api-references) section. - -This component uses Material Icons. Add the following link to your `index.html`: `` - +| Property | Type | Default | Description | +| --- | --- | --- | --- | +| `shape` | `"square" \| "rounded" \| "circle"` | `"square"` | Sets the shape of the avatar. | +| `size` | `"small" \| "medium" \| "large"` | `"small"` | Sets the size of the avatar. | +| `initials` | `string` | — | Text initials rendered when no image or icon is set. | +| `icon` | `string` | — | Icon name to render via [`igx-icon`](/icon). | +| `src` | `string` | — | Image source URL to render. | +| `id` | `string` | `"igx-avatar-{n}"` | The unique identifier of the avatar. | -You should see something like this: +## Styling - + -## Styling +The avatar's appearance is controlled through the parameters below. Set `$background`, and the contrast-dependent colors (`$color` and `$icon-color`) are derived automatically. -### Avatar Theme Property Map +| Variable | Description | +| --- | --- | +| `$background` | The avatar background color. Primary token — derives `$color` and `$icon-color`. | +| `$color` | The text/initials color. Auto-derived from `$background` for contrast when not set. | +| `$icon-color` | The icon color. Auto-derived from `$background` for contrast when not set. | +| `$border-radius` | The border radius. Only takes effect when `shape` is `rounded`. | +| `$size` | The size of the avatar. | -Changing the `$background` property automatically updates the following dependent properties: +### Sass Theming -| Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$background** | $color | The text color used for the avatar. | -| | $icon-color | The icon color used for the avatar. | +#### Using SCSS -To get started with styling the avatar, we need to import the `index` file, where all the theme functions and component mixins live: +To get started with styling the avatar, import the theme entry point where all the theme functions and component mixins live: ```scss @use "igniteui-angular/theming" as *; - -// IMPORTANT: Prior to Ignite UI for Angular version 13 use: -// @import '~igniteui-angular/lib/core/styles/themes/index'; ``` -Following the simplest approach, we create a new theme that extends the providing values for the `$background` and `$border-radius` parameters. The `$color` (or `$icon-color`) is automatically set to either black or white, depending on which offers better contrast with the specified background. Note that the `$border-radius` property only takes effect when the avatar's `shape` is set to `rounded`. +Create a new theme that extends the , providing values for the `$background` and `$border-radius` parameters. The `$color` (or `$icon-color`) is automatically set to either black or white, depending on which offers better contrast with the specified background. Note that `$border-radius` only takes effect when the avatar's `shape` is set to `rounded`. Given the following markup: ```html -
- - +
+
``` -We create the following avatar theme: +Create the theme: ```scss $custom-avatar-theme: avatar-theme( - $background: #72da67, - $border-radius: 16px + $background: #72da67, + $border-radius: 16px ); ``` -The last step is to pass the custom avatar theme: +Then apply it to your markup: ```scss -.initials { - @include tokens($custom-avatar-theme); +.my-container:has(igx-avatar[initials]) { + @include tokens($custom-avatar-theme); } ``` -If all went well, you should see something like the following in the browser: +#### Using pure CSS - +Prefer not to use SCSS? Override the component's CSS variables directly: -### Styling with Tailwind +```css +/* overrides all avatars */ +:root { + --ig-avatar-background: #e41c77; +} -You can style the `avatar` using our custom Tailwind utility classes. Make sure to [set up Tailwind](/themes/misc/tailwind-classes) first. +/* overrides only the avatar with class .special */ +igx-avatar.special { + --background: #e41c77; +} +``` + +### Tailwind + +You can style the avatar using our Tailwind utility classes. Make sure to [set up Tailwind](/themes/misc/tailwind-classes) first. -Along with the tailwind import in your global stylesheet, you can apply the desired theme utilities as follows: +With the Tailwind import in your global stylesheet, apply the theme utilities: ```scss @import "tailwindcss"; @@ -223,25 +222,23 @@ The utility file includes both `light` and `dark` theme variants. - Use `dark-*` classes for the dark theme. - Append the component name after the prefix, e.g., `light-avatar`, `dark-avatar`. -Once applied, these classes enable dynamic theme calculations. From there, you can override the generated CSS variables using `arbitrary properties`. After the colon, provide any valid CSS color format (HEX, CSS variable, RGB, etc.). +Once applied, these classes enable dynamic theme calculations. From there, override the generated CSS variables using Tailwind's arbitrary-property syntax — for example `[--background:#FF4E00]` — with any valid CSS color format (HEX, CSS variable, RGB, etc.). -You can find the full list of properties in the . The syntax is as follows: +See the for the full list of parameters. For example: ```html + class="!light-avatar ![--background:#FF4E00]" + initials="DY" + shape="rounded"> ``` -The exclamation mark(`!`) is required to ensure the utility class takes precedence. Tailwind applies styles in layers, and without marking these styles as important, they will get overridden by the component’s default theme. +The exclamation mark(`!`) is required to ensure the utility class takes precedence. Tailwind applies styles in layers, and without marking these styles as important, they will get overridden by the component's default theme. -At the end your avatar should look like this: - - + ### Custom sizing @@ -257,7 +254,6 @@ Or you can use the universal `--ig-avatar-size` variable to target all instances ```html
-
``` @@ -268,7 +264,7 @@ Or you can use the universal `--ig-avatar-size` variable to target all instances } ``` -You can also use one of the predefined sizes, assigning it to the `--ig-size` variable, if theres no size attribute applied. The available values for `--ig-size` are `--ig-size-small`, `--ig-size-medium`, and `--ig-size-large`: +You can also use one of the predefined sizes by assigning it to the `--ig-size` variable, if no `size` attribute is set. The available values for `--ig-size` are `--ig-size-small`, `--ig-size-medium`, and `--ig-size-large`: ```scss igx-avatar { @@ -276,22 +272,80 @@ igx-avatar { } ``` -Learn more about it in the [Size](/display-density) article. +Learn more in the [Size](/display-density) article. + +## Accessibility + +### Keyboard Interaction + +The avatar is a non-interactive, presentational element — it doesn't receive focus and has no keyboard interaction to document. + +### Screen Readers / ARIA + +The avatar renders with `role="img"` and a default `aria-label` of `avatar`, and it automatically sets `aria-roledescription` to reflect its content — `image avatar`, `icon avatar`, `initials avatar`, or `custom avatar` for projected content. + +When the avatar carries meaning — such as identifying a specific person — set a descriptive `aria-label` so screen-reader users get the same information sighted users get from the image, icon, or initials: + +```html + +``` + +If the avatar is purely decorative and its meaning is already conveyed by adjacent text (for example, a name shown next to it), keep the label minimal so the same information isn't announced twice. + +### Accessibility Compliance + +Infragistics evaluates Ignite UI for Angular components against Section 508 and WCAG guidelines — see the [Accessibility Compliance](/interactivity/accessibility-compliance) topic for the full component-by-component matrix. + +| Criterion | How the Avatar complies | +| --- | --- | +| [1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html) | The default `aria-label="avatar"` gives every avatar an accessible name; set your own `aria-label` when the image, icon, or initials convey specific meaning (e.g. a person's identity). | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) | The host element exposes `role="img"` and an `aria-roledescription` (`image avatar`, `icon avatar`, `initials avatar`, or `custom avatar`) reflecting its current content. | + +**Your responsibilities** + +- Provide a descriptive `aria-label` whenever the avatar identifies a specific person or entity. +- Keep sufficient color contrast between the avatar's background and its text/icon color when customizing the theme — see [Styling](#styling). + +## Troubleshooting + +### Why doesn't the `roundShape` property work anymore? + +`roundShape` was replaced by `shape` in `15.1.0`. Run `ng update` to migrate existing usages automatically, or update them by hand — `shape="circle"` replaces `roundShape="true"`, and `shape="square"` (the default) replaces `roundShape="false"`. + +### How do I use the avatar in a module-based (NgModule) app? + +Standalone is the default in modern Angular, and Ignite UI for Angular components support it since `16.0.0`. In an older, module-based application, import `IgxAvatarModule` and add it to your `@NgModule` `imports` array instead of importing the component directly: + +```typescript +// app.module.ts +import { IgxAvatarModule } from 'igniteui-angular/avatar'; +// import { IgxAvatarModule } from '@infragistics/igniteui-angular'; for licensed package + +@NgModule({ + imports: [IgxAvatarModule], +}) +export class AppModule {} +``` + +### Why does my theme import fail on older versions? + +The `@use "igniteui-angular/theming" as *;` entry point was introduced in v13. On earlier versions, import the themes index instead: -
+```scss +@import '~igniteui-angular/lib/core/styles/themes/index'; +``` ## API References -
+ - -## Theming Dependencies + +## Dependencies - - ## Additional Resources -
- Our community is active and always welcoming to new ideas. - [Ignite UI for Angular **Forums**](https://www.infragistics.com/community/forums/f/ignite-ui-for-angular) diff --git a/docs/angular/src/content/en/components/calendar.mdx b/docs/angular/src/content/en/components/calendar.mdx index 0a61a83248..7c64935b01 100644 --- a/docs/angular/src/content/en/components/calendar.mdx +++ b/docs/angular/src/content/en/components/calendar.mdx @@ -1,8 +1,9 @@ --- -title: Angular Calendar Component – Ignite UI for Angular | MIT license -description: With Angular Calendar Component, users can create intuitive calendars for applications to display date information using three different selection modes. Try it Now +title: Angular Calendar Component – Ignite UI for Angular | MIT license +description: The Angular Calendar component displays dates with single, multiple, or range selection, localization, disabled and special dates, and multiple views. keywords: angular calendar, angular calendar component, angular UI components, angular UI library, ignite ui for angular license: MIT +relatedComponents: [DatePicker, DateRangePicker] llms: description: "Angular Calendar is a UI component used for displaying dates and days in an app." --- @@ -11,59 +12,47 @@ import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro' import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# Angular Calendar Component Overview +# Calendar Component -Angular Calendar is a UI component used for displaying dates and days in an app. Supporting different features, it enables users to easily manage calendar functionalities, drag and create events in a calendar, navigate to a preferred date in it, and show events in an Angular calendar month view, week view, or day view in a single click. +Angular Calendar is a UI component used for displaying dates and days in an app. It renders a month, year, or decade view and lets users select a single date, multiple dates, or a date range, with support for localization, disabled dates, and special dates. -
+## Overview -The Ignite UI for Angular Calendar component, developed as a native [Angular component](https://angular.io/guide/architecture#components), provides an easy and intuitive ways to display date information, enable dates or apply Angular calendar disable dates mode. Users can choose from three different selection modes - single selection, multi selection or range selection. -
+### When to Use -## Angular Calendar Example +Use the Calendar when you need an always-visible date surface embedded in the page — a scheduling panel, an availability view, or a form that benefits from selecting single dates, multiple dates, or a range directly in the layout. -We created the following Angular Calendar example using the Ignite UI for Angular Calendar package. It quickly shows how a basic calendar looks and feels like, how users can choose and highlight a single date, and how to move back and forth to a specific date. +### When Not to Use -
+- To bind a single date to a text input in a compact dropdown, use the — it hosts a calendar in a drop-down and exposes the value through an input. +- To capture a start/end pair bound to inputs, use the instead of wiring range selection onto a bare calendar. - + -## Getting Started with Ignite UI for Angular Calendar +## Anatomy -To get started with the Ignite UI for Angular Calendar component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: +{/* TODO: add an annotated screenshot of the calendar parts (header, navigation subheader, days grid). */} -```cmd -ng add igniteui-angular +The calendar renders a header, a navigation subheader, and a view area that swaps between the days, months, and years views. The header is hidden when `selection` is `multi` or `range`. + +``` +igx-calendar +├── Header // selected date; hidden for multi/range selection +├── Navigation subheader // previous button · month button · year button · next button +└── View area (role="grid") + ├── igx-days-view // day grid for the current month(s) + ├── igx-months-view // month picker + └── igx-years-view // decade (year) picker ``` -For a complete introduction to the Ignite UI for Angular, read the [_getting started_](/general/getting-started) topic. +## Getting Started -The next step is to import the `IgxCalendarModule` in your **app.module.ts** file. +Requires Ignite UI for Angular — see [Getting Started](/general/getting-started) (`ng add igniteui-angular`). - -The also depends on the [`BrowserAnimationsModule`](https://angular.io/api/platform-browser/animations/BrowserAnimationsModule), so it needs to be added to the AppModule as well: - - -```typescript -// app.module.ts -... -import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; -import { IgxCalendarModule } from 'igniteui-angular/calendar'; -// import { IgxCalendarModule } from '@infragistics/igniteui-angular'; for licensed package - -@NgModule({ - ... - imports: [..., BrowserAnimationsModule, IgxCalendarModule], - ... -}) -export class AppModule {} -``` - -Alternatively, as of `16.0.0` you can import the `IgxCalendarComponent` as a standalone dependency, or use the [`IGX_CALENDAR_DIRECTIVES`](https://github.com/IgniteUI/igniteui-angular/blob/master/projects/igniteui-angular/calendar/src/calendar/public_api.ts) token to import the component and all of its supporting components and directives. +Import `IGX_CALENDAR_DIRECTIVES` in the component where you use the calendar. The calendar also depends on `BrowserAnimationsModule`, so add it to the same `imports`: ```typescript // home.component.ts - import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; import { IGX_CALENDAR_DIRECTIVES } from 'igniteui-angular/calendar'; // import { IGX_CALENDAR_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package @@ -72,72 +61,66 @@ import { IGX_CALENDAR_DIRECTIVES } from 'igniteui-angular/calendar'; selector: 'app-home', template: '', styleUrls: ['home.component.scss'], - standalone: true, imports: [BrowserAnimationsModule, IGX_CALENDAR_DIRECTIVES] - /* or imports: [BrowserAnimationsModule, IgxCalendarComponent] */ }) export class HomeComponent {} ``` -Now that you have the Ignite UI for Angular Calendar module or directives imported, you can start using the `igx-calendar` component. +The `IGX_CALENDAR_DIRECTIVES` token imports the together with its views and supporting directives. To register the calendar on its own, import `IgxCalendarComponent` instead. For the legacy `NgModule` setup, see [Troubleshooting](#troubleshooting). -The uses the [Intl Web API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) for localization and formatting of dates. +The uses the [Intl Web API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) for localization and formatting of dates. Consider using [appropriate polyfills](https://github.com/andyearnshaw/Intl.js/) if your target platform does not support them. -Consider using [appropriate polyfills](https://github.com/andyearnshaw/Intl.js/) if your target platform does not support them. -## Using the Angular Calendar +## Usage -### Angular Single Selection Calendar +### Single selection -Instantiating the `IgxCalendarComponent` is as easy as placing its selector element in the template. This will display the current month in the single selection calendar mode. +Place the `igx-calendar` selector in the template. With no `selection` set, the calendar renders the current month in single selection mode: ```html {/* app.component.html */} -{/* Single selection mode */} ``` -### Angular Calendar Multiselect +### Multiple selection -We can easily change the default mode using the property: +Set the property to `multi` to let users pick several individual dates: ```html {/* app.component.html */} -{/* Multi selection mode */} ``` - + -### Angular Calendar Range Picker +### Range selection -Following the same approach, we can switch to range selection mode: +Set `selection` to `range` to let users pick a continuous range between two dates: ```html {/* app.component.html */} -{/* Range selection mode */} ``` - + -Notice that the calendar header is not rendered when the selection is either `multi` or `range`. +The calendar header is not rendered when `selection` is either `multi` or `range`. -### Localization and Formatting +### Localization and formatting -Due to their very nature, localization and formatting are essential to any calendar. In the `IgxCalendarComponent` those are controlled and customized through the following properties - , , , . +Control localization and formatting through , , , and . -Let's go ahead and try those along with other customizations from the `IgxCalendarComponent API`. First thing we need to set is the `weekStart`, which controls the starting day of the week. It defaults to 0, which corresponds to Sunday, so we will set a value of 1 for Monday. In the markup below we are also binding the `formatOptions` and `formatViews` properties to customize the display formatting. Finally, we are binding the `locale` property to a value, based on the user's location choice: +`weekStart` sets the starting day of the week. If you don't set it, the calendar uses the first day of the week for its `locale`. Set it to `1` for Monday. `formatOptions` and `formatViews` customize how the day, month, and year are rendered, and `locale` sets the language: ```html {/* app.component.html */} - - {{ locale }} - + @for (locale of locales; track locale) { + {{ locale }} + } ``` -All property values should be set in the AppComponent file: +Set the bound values in the component: ```typescript // app.component.ts @@ -165,17 +148,13 @@ public ngOnInit() { } ``` -If everything went well, we should now have a calendar with customized dates display, that also changes the locale representation, based on the user location. Let's have a look at it: - - + -### How to Disable Dates In Angular Calendar +### Disabled dates -This section demonstrates the usage of functionality. For this purpose, different single dates or ranges can be added to an array and then passed to the `disabledDates` descriptor. +Assign an array of descriptors to to prevent dates from being selected. Use to describe the range to disable. -The is used to specify a range that is going to be disabled. - -Let's create a sample that is disabling the dates between the 3rd and the 8th of the current month: +Disable the dates between the 3rd and the 8th of the current month: ```typescript export class CalendarSample6Component { @@ -192,15 +171,11 @@ export class CalendarSample6Component { } ``` -These configurations should have the following result: - - + ### Special dates -The feature is using almost the same configuration principles as the `disabledDates`. The ability to select and focus `specialDates` is what differs them from the `disabled` ones. - -Let's add some `specialDates` to our `igxCalendar`. In order to do this, we have to create a item of type and pass an array of dates as a : + uses the same descriptor configuration as `disabledDates`, but special dates stay selectable and focusable. Create a of type and pass an array of dates as its : ```typescript export class CalendarSample7Component { @@ -239,165 +214,44 @@ export class CalendarSample7Component { ``` -The following demo illustrates a calendar with a vacation request option: - - + ### Week numbers -You can now use input to show the week numbers for both Calendar and DatePicker components. +Set to `true` to display week numbers. The same input applies to the Date Picker. ```html - {/* app.component.html */} ``` -The following demo illustrates a calendar with enabled week numbers: - - - -## Calendar Events - -Let's explore the events emitted by the calendar: - -- - emitted when selecting date(s) in the calendar. -- - emitted every time when the presented month/year is changed - for example after navigating to the `next` or `previous` month. -- - emitted after the active view is changed - for example after the user has clicked on the `month` or `year` section in the header. - -```html -{/* app.component.html */} - - -``` - -The event is suitable to build input validation logic. Use the code from below to alert the user if selection exceeds 5 days, and then reset the selection: - -```typescript -// app.component.ts -... -public onSelection(dates: Date[]) { - if (dates.length > 5) { - this.calendar.selectedDates = []; - // alert the user - } -} -public viewDateChanged(event: IViewDateChangeEventArgs) { - // use event.previousValue to get previous month/year that was presented. - // use event.currentValue to get current month/year that is presented. -} - -public activeViewChanged(event: CalendarView) { - // use CalendarView[event] to get the current active view (DEFAULT, YEAR or DECADE) -} -``` - -Use the demo below to play around (change selection, navigate through months and years) and see the events logged real time: - - - -## Angular Calendar Views - -There are separate views provided by the `IgxCalendarModule` that can be used independently: - -- Angular Calendar Days View - - - + -- Angular Calendar Month View - +### Views - +The days, months, and years views ship as standalone components you can use independently of the full calendar: -- Angular Calendar Year View - +- — the day grid. - + -## Keyboard navigation +- — the month picker. -If you traverse the page using _Tab key_ you should keep in mind that based on [W3 accessibility recommendations](https://www.w3.org/TR/wai-aria-practices/#layoutGrid) the _igxCalendarComponent_ now introduces the following tab stops: + -- Previous month button -- Month selection button -- Year selection button -- Next month button -- Selected date, Current date, First focusable (not disabled) date in the days view - -In an Angular Calendar that contains more than one selected dates, only the first date will be introduced as a tab stop. For example, when an Angular Calendar multi-select is enabled and you have selected the dates: _13/10/2020_, _17/10/2020_ and _21/10/2020_ only _13/10/2020_ will be accessible during tab navigation; in an Angular Calendar Range Picker, only the first date of the selected range will be part of the _page tab sequence_. - - -Behavioral change, from _v10.2.0_ - Tab key navigation in the _days view_ is no longer available. In order to navigate between the dates in the _date view_ you should use the _arrow keys_. - - -When the `igxCalendar` component is focused, use: - -- PageUp key to move to the previous month, -- PageDown key to move to the next month, -- Shift + PageUp keys to move to the previous year, -- Shift + PageDown keys to move to the next year, -- Home key to focus the first day of the current month or first month in view -- End key to focus the last day of the current month or last month in view - -When the `prev` or the `next` month buttons (in the subheader) are focused, use: - -- Space or Enter key to scroll into view the next or previous month. - -When the `months` button (in the subheader) is focused, use: - -- Space or Enter key to open the months view. - -When the `year` button (in the subheader) is focused, use: - -- Space or Enter key to open the decade view. - -When a `day` inside the current month is focused: - -- Use _Arrow keys_ to navigate through the days. Note: The disabled dates will be skipped. -- Focus will be persisted on the current month that is in the view, while navigation **from**/**to** the **last day**/**first day** of the month. -- THe kb navigation would be continuous, which means that it will go through all months while navigating with the arrows. -- Use Enter key to select the currently focused day. - -When a `month` inside the months view is focused, use: - -- Arrow keys to navigate through the months. -- Home key to focus the first month inside the months view. -- End key to focus the last month inside the months view. -- Enter key to select the currently focused month and close the view. - -When an `year` inside the decade view is focused, use: - -- Arrow up and Arrow down keys to navigate through the years, -- Enter key to select the currently focused year and close the view. - - -Following version 8.2.0, keyboard navigation will not focus days that are outside of current month, but will rather change the month in view. - +- — the year picker. -## Multi View Calendar + -Multi-view calendar supports all three types of selection. Use the input to set the number of displayed months, which will be shown horizontally in a flex container. There is no limit on the max value set. While using a multi view calendar, you may want to hide the days that do not belong to the current month. You are able to do it with the property. Keyboard navigation moves to next/previous months when those are in view. +### Multi-view - +Set to render several months side by side in a flex container; multi-view supports all three selection types. There is no maximum value. Set to `true` to hide days that don't belong to the current month, and keyboard navigation moves to the next or previous month when it is in view. -## Calendar Orientation + -The orientation settings allows users to choose how the header and the view of the calendar are displayed. +### Orientation -### Header Orientation Options - -You can change the header orientation to place the header of the calendar to be either horizontal(above the calendar view) or vertical(on the side of the calendar view). -To do that, use the `[headerOrientation]` property, setting it respectively to `horizontal` or `vertical` - -### View Orientation Options - -You can set the view orientation to place the months in the calendar either horizontally(side by side) or vertically(above one another). -To do that, use the `[orientation]` property, setting it respectively to `horizontal` or `vertical`. - - -You need at least two month view calendar to see that property working. - +Set `headerOrientation` to place the header `horizontal` (above the view) or `vertical` (beside the view). Set `orientation` to lay the months out `horizontal` (side by side) or `vertical` (stacked). Both default to `horizontal`. ```html @@ -422,234 +276,239 @@ export class CalendarSample9Component { } ``` - + +Set `monthsViewNumber` to at least `2` to see the `orientation` setting take effect. + -## Styling + -### Calendar Theme Property Map +### Handling events -When you modify the `$header-background` and `$content-background` properties, all related theme properties are automatically adjusted to ensure your calendar component is styled consistently. See the tables below for a detailed overview of which theme properties are affected. +Bind to the calendar events to react to selection and navigation: -
+```html +{/* app.component.html */} + + +``` -{/*Theme Switcher Radios and Labels*/} - - - - - - - - +The event emits a single `Date` in `single` selection and a `Date[]` in `multi` or `range` selection, so it is a good place for validation. Alert the user when the selection exceeds 5 days and then reset it: -
+```typescript +// app.component.ts +public onSelection(dates: Date[]) { + if (dates.length > 5) { + this.calendar.selectedDates = []; + // alert the user + } +} +public viewDateChanged(event: IViewDateChangeEventArgs) { + // use event.previousValue to get the previously presented month/year. + // use event.currentValue to get the currently presented month/year. +} - {/* Material Theme Table */} -
+public activeViewChanged(event: CalendarView) { + // use CalendarView[event] to get the current active view (DEFAULT, YEAR or DECADE) +} +``` - | Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$header-background** | $header-foreground | Text color for the calendar header | -| | $picker-hover-foreground | Picker hover foreground | -| | $picker-focus-foreground | Picker focus foreground | -| | $navigation-hover-color | Hover color for navigation | -| | $navigation-focus-color | Focus color for navigation | -| | $date-selected-background | Background for selected dates | -| | $date-selected-current-background | Selected current date background | -| | $date-selected-foreground | Foreground for selected dates | -| | $date-selected-current-foreground | Foreground for selected current date | -| | $date-selected-current-border-color | Border color for selected current date | -| | $date-selected-special-border-color | Border color for selected special dates | -| | $ym-selected-background | Year/month selected background | -| | $ym-selected-hover-background | Hover background for year/month selected date | -| | $ym-selected-current-background | Current selected year/month background | -| | $ym-selected-current-hover-background | Hover background for current selected year/month | -| | $ym-selected-foreground | Foreground for selected year/month | -| | $ym-selected-hover-foreground | Hover foreground for selected year/month | -| | $ym-selected-current-foreground | Foreground for current selected year/month | -| | $ym-selected-current-hover-foreground | Hover foreground for current selected year/month | -| **$content-background** | $content-foreground | Text and icon color inside calendar content area | -| | $weekend-color | Color for weekend dates | -| | $inactive-color | Color for dates outside active range | -| | $weekday-color | Color for weekday labels | -| | $picker-background | Picker background | -| | $date-hover-background | Background for hovered dates | -| | $date-hover-foreground | Foreground for hovered dates | -| | $date-focus-background | Background for focused dates | -| | $date-focus-foreground | Foreground for focused dates | -| | $date-current-background | Background for the current date | -| | $date-current-foreground | Foreground for the current date | -| | $date-current-border-color | Border color for the current date | -| | $ym-current-background | Year/month current background | -| | $ym-current-hover-background | Hover background for current year/month | -| | $ym-current-foreground | Foreground for current year/month | -| | $ym-current-hover-foreground | Hover foreground for current year/month | -| | $date-selected-range-background | Selected range background | -| | $date-selected-range-foreground | Foreground for selected date ranges | -| | $date-selected-current-range-background | Background for selected current date ranges | -| | $date-selected-current-range-hover-background | Hover background for selected current date ranges | -| | $date-selected-current-range-focus-background | Focus background for selected current date ranges | -| | $date-selected-current-range-foreground | Foreground for selected current date ranges | -| | $date-special-foreground | Foreground for special dates | -| | $date-special-border-color | Border color for special dates | -| | $date-special-hover-border-color | Hover border color for special dates | -| | $date-special-focus-foreground | Focus foreground for special dates | -| | $date-special-range-foreground | Foreground for special date ranges | -| | $date-special-range-border-color | Border color for special date ranges | -| | $date-special-range-hover-background | Hover background for special date ranges | -| | $date-selected-special-border-color | Border color for selected special dates | -| | $date-selected-special-hover-border-color | Hover border color for selected special dates | -| | $date-selected-special-focus-border-color | Focus border color for selected special dates | -| | $date-disabled-foreground | Foreground for disabled dates | -| | $date-disabled-range-foreground | Foreground for disabled ranges | -| **$date-border-radius** | $date-range-border-radius | Controls the border radius for date ranges. | -| | $date-current-border-radius | Controls the border radius for the current date. | -| | $date-special-border-radius | Controls the border radius for special dates. | -| | $date-border-radius | If not specified and `$date-range-border-radius` is set, uses the value of `$date-range-border-radius`. | - -
- {/* Fluent Theme Table */} -
- - | Primary Property | Dependent Property | Description | + + +## Best Practices + +- Match the `selection` mode to the real task — `single` for one date, `multi` for scattered individual picks, `range` for a start/end pair — instead of layering custom logic onto the wrong mode. +- Use `disabledDates` and `specialDates` to communicate availability directly in the grid rather than relying on separate legend text the user has to cross-reference. +- Set `weekStart` and `locale` together when localizing — leaving `weekStart` unset lets the calendar infer it from `locale`, so setting one without the other can produce a week layout that doesn't match the surrounding page's language. +- Don't embed a full Calendar just to capture one date bound to a text field — use the Date Picker instead (see [When Not to Use](#when-not-to-use)). + +## Properties + +{/* Curated core inputs, verified from IgxCalendarComponent. See API References for the complete list. */} + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `selection` | `'single' \| 'multi' \| 'range'` | `'single'` | Selection mode. Changing it resets the current selection. | +| `value` | `Date \| Date[]` | — | Selected date(s): a single `Date` for `single`, otherwise a `Date[]`. | +| `viewDate` | `Date` | current date | The date presented when the calendar renders. | +| `weekStart` | `WEEKDAYS \| number` | locale's first day | Starting day of the week; falls back to the `locale`'s first day. | +| `locale` | `string` | application locale | BCP 47 language tag used for formatting. | +| `formatOptions` | `IFormattingOptions` | `{ day: 'numeric', month: 'long', weekday: 'narrow', year: 'numeric' }` | `Intl` date-format options per view. | +| `formatViews` | `IFormattingViews` | `{ day: false, month: true, year: false }` | Which views apply `formatOptions`. | +| `disabledDates` | `DateRangeDescriptor[]` | `[]` | Ranges that cannot be selected. | +| `specialDates` | `DateRangeDescriptor[]` | `[]` | Highlighted ranges that remain selectable. | +| `showWeekNumbers` | `boolean` | `false` | Displays the week numbers column. | +| `hideOutsideDays` | `boolean` | `false` | Hides days that fall outside the current month. | +| `monthsViewNumber` | `number` | `1` | Number of month views rendered side by side. | +| `hasHeader` | `boolean` | `true` | Renders the calendar header (single selection only). | +| `headerOrientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Header placement relative to the view. | +| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction of the month views. | +| `activeView` | `IgxCalendarView` | `'month'` | The view in focus (`month`, `year`, or `decade`). | + +## Methods + +| Name | Parameters | Description | | --- | --- | --- | -| **$header-background** | $header-foreground | Text color for the calendar header | -| | $picker-hover-foreground | Picker hover foreground | -| | $picker-focus-foreground | Picker focus foreground | -| | $date-current-background | Background for the current date | -| | $date-current-hover-foreground | Hover foreground for the current date | -| | $date-current-focus-foreground | Focus foreground for the current date | -| | $date-selected-current-foreground | Foreground for the currently selected date | -| | $date-selected-current-hover-foreground | Hover foreground for the currently selected date | -| | $date-selected-current-focus-foreground | Focus foreground for the currently selected date | -| | $date-special-border-color | Border color for special dates | -| | $date-special-hover-foreground | Hover foreground for special dates | -|**$content-background** | $content-foreground | Text and icon color inside calendar content area | -| | $weekend-color | Color for weekend dates | -| | $inactive-color | Color for dates outside active range | -| | $weekday-color | Color for weekday labels | -| | $picker-background | Picker background | -| | $date-hover-background | Background for hovered dates | -| | $date-hover-foreground | Foreground for hovered dates | -| | $date-focus-background | Background for focused dates | -| | $date-focus-foreground | Foreground for focused dates | -| | $date-selected-background | Background for selected dates | -| | $date-selected-hover-background | Hover background for selected dates | -| | $date-selected-focus-background | Focus background for selected dates | -| | $date-selected-foreground | Foreground for selected dates | -| | $date-selected-hover-foreground | Hover foreground for selected dates | -| | $date-selected-focus-foreground | Focus foreground for selected dates | -| | $date-selected-range-background | Background for selected date ranges | -| | $date-selected-range-foreground | Foreground for selected date ranges | -| | $date-disabled-foreground | Foreground for disabled dates | -| | $date-disabled-range-foreground | Foreground for disabled ranges | -| **$date-border-radius** | $date-range-border-radius | Controls the border radius for date ranges. | -| | $date-current-border-radius | Controls the border radius for the current date. | -| | $date-special-border-radius | Controls the border radius for special dates. | -| | $date-border-radius | If not specified and `$date-range-border-radius` is set, uses the value of `$date-range-border-radius`. | - -
- {/* Bootstrap Theme Table */} -
- - | Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$header-background** | $header-foreground | Text color for the calendar header | -| | $picker-background | Picker background | -| | $picker-hover-foreground | Picker hover foreground | -| | $weekday-color | Color for weekday labels | -| | $picker-focus-foreground | Picker focus foreground | -| | $date-special-border-color | Border color for special dates | -| | $date-special-focus-foreground | Focus foreground for special dates | -| **$content-background** | $content-foreground | Text and icon color inside calendar content area | -| | $weekend-color | Color for weekend dates | -| | $inactive-color | Color for dates outside active range | -| | $weekday-color | Color for weekday labels | -| | $date-hover-background | Background for hovered dates | -| | $date-hover-foreground | Foreground for hovered dates | -| | $date-focus-background | Background for focused dates | -| | $date-focus-foreground | Foreground for focused dates | -| | $date-current-background | Background for the current date | -| | $date-current-foreground | Foreground for the current date | -| | $date-current-border-color | Border color for the current date | -| | $date-selected-background | Background for selected dates | -| | $date-selected-current-background | Background for the currently selected date | -| | $date-selected-foreground | Foreground for selected dates | -| | $date-selected-current-foreground | Foreground for the currently selected date | -| | $date-selected-special-border-color | Border color for selected special dates | -| | $date-selected-special-hover-border-color | Hover border color for selected special dates | -| | $date-selected-special-focus-border-color | Focus border color for selected special dates | -| | $date-selected-range-background | Background for selected date ranges | -| | $date-selected-range-foreground | Foreground for selected date ranges | -| | $date-disabled-foreground | Foreground for disabled dates | -| | $date-disabled-range-foreground | Foreground for disabled ranges | -| **$date-border-radius** | $date-range-border-radius | Controls the border radius for date ranges. | -| | $date-current-border-radius | Controls the border radius for the current date. | -| | $date-special-border-radius | Controls the border radius for special dates. | -| | $date-border-radius | If not specified and `$date-range-border-radius` is set, uses the value of `$date-range-border-radius`. | - -
- {/* Indigo Theme Table */} -
- - | Primary Property | Dependent Property | Description | +| `selectDate` | `value: Date \| Date[] \| string` | Selects date(s) according to the current `selection` mode. | +| `deselectDate` | `value?: Date \| Date[] \| string` | Deselects date(s); clears the whole selection when called with no argument. | + +## Events + +| Name | Type | Description | | --- | --- | --- | -| **$header-background** | $header-foreground | Text color for the calendar header | -| | $picker-background | Picker background | -| | $picker-hover-foreground | Picker hover foreground | -| | $picker-focus-foreground | Picker focus foreground | -| | $navigation-hover-color | Navigation hover color | -| | $navigation-focus-color | Navigation focus color | -| | $date-current-background | Background for the current date | -| | $date-current-border-color | Border color for the current date | -| | $date-current-hover-background | Background for hovered current date | -| | $date-current-hover-border-color | Border color for hovered current date | -| | $date-current-focus-background | Background for focused current date | -| | $date-current-focus-border-color | Border color for focused current date | -| | $date-current-foreground | Foreground for the current date | -| | $date-current-hover-foreground | Foreground for hovered current date | -| | $date-current-focus-foreground | Foreground for focused current date | -| | $date-selected-current-border-color | Border color for the currently selected date | -| **$content-background** | $content-foreground | Text and icon color inside calendar content area | -| | $weekend-color | Color for weekend dates | -| | $inactive-color | Color for dates outside active range | -| | $weekday-color | Color for weekday labels | -| | $date-hover-background | Background for hovered dates | -| | $date-hover-foreground | Foreground for hovered dates | -| | $date-focus-background | Background for focused dates | -| | $date-focus-foreground | Foreground for focused dates | -| | $date-selected-background | Background for selected dates | -| | $date-selected-current-background | Background for the currently selected date | -| | $date-selected-foreground | Foreground for selected dates | -| | $date-selected-current-foreground | Foreground for the currently selected date | -| | $date-selected-current-border-color | Border color for the currently selected date | -| | $date-selected-range-background | Background for selected date ranges | -| | $date-selected-range-foreground | Foreground for selected date ranges | -| | $date-selected-current-range-background | Background for the current date in a selected range | -| | $date-selected-current-range-hover-background | Hover background for the current date in a selected range | -| | $date-selected-current-range-foreground | Foreground for the current date in a selected range | -| | $date-disabled-foreground | Foreground for disabled dates | -| | $date-disabled-range-foreground | Foreground for disabled ranges | -| **$date-border-radius** | $date-range-border-radius | Controls the border radius for date ranges. | -| | $date-current-border-radius | Controls the border radius for the current date. | -| | $date-special-border-radius | Controls the border radius for special dates. | -| | $date-border-radius | If not specified and `$date-range-border-radius` is set, uses the value of `$date-range-border-radius`. | - -
- -
-
{/* .theme-switcher-wrapper */} - -To get started with styling the calendar, we need to import the `index` file, where all the theme functions and component mixins live: +| `selected` | `EventEmitter` | Emitted when date(s) are selected. | +| `viewDateChanged` | `EventEmitter` | Emitted when the presented month or year changes. | +| `activeViewChanged` | `EventEmitter` | Emitted when the active view changes (for example, from month to year). | + +## Styling + +Style the calendar by creating a theme and passing it to the component. The sample below applies a custom `$header-background` and `$content-background`: + + + +All themes expose the same set of variables — only their default values differ per theme. Many of them auto-derive from the primary properties (`$header-background`, `$content-background`) when not set explicitly, so the component stays visually consistent. + +| Variable | Description | +| --- | --- | +| `$size` | Size of days, months, and years views. | +| `$inner-size` | Inner size for calendar elements. | +| `$weekday-color` | Color for weekday labels. Auto-derived from content-background. | +| `$actions-divider-color` | Divider color for date-picker actions. | +| `$border-radius` | Border radius for calendar container. | +| `$content-background` | Background color for calendar. PRIMARY - derives content-foreground, inactive-color, date-hover colors, week-number colors. | +| `$border-color` | Border color for calendar container. | +| `$header-background` | Header background color. PRIMARY - derives header-foreground and most accent/selection colors. | +| `$header-foreground` | Header foreground color. Auto-derived from header-background. | +| `$picker-foreground` | Foreground for the calendar picker. Auto-derived from picker-background. | +| `$picker-background` | Background for the calendar picker. | +| `$picker-hover-foreground` | Hover foreground for the calendar picker. Auto-derived from header-background. | +| `$picker-focus-foreground` | Focus foreground for the calendar picker. Auto-derived from picker-hover-foreground. | +| `$navigation-color` | Icon color for month navigation. Auto-derived from picker-background. | +| `$navigation-hover-color` | Hover color for navigation icons. Auto-derived from picker-hover-foreground. | +| `$navigation-focus-color` | Focus color for navigation icons. Auto-derived from navigation-hover-color. | +| `$ym-border-radius` | Border radius for year/month views. | +| `$ym-hover-foreground` | Hover foreground for year/month. Auto-derived from ym-hover-background. | +| `$ym-hover-background` | Hover background for year/month. Auto-derived from date-hover-background. | +| `$ym-current-outline-color` | Outline color for current year/month. Auto-derived from date-current-border-color. | +| `$ym-current-outline-hover-color` | Hover outline color for current year/month. | +| `$ym-current-outline-focus-color` | Focus outline color for current year/month. | +| `$ym-current-background` | Background for current year/month. | +| `$ym-current-foreground` | Foreground for current year/month. Auto-derived from ym-current-background. | +| `$ym-current-hover-foreground` | Hover foreground for current year/month. | +| `$ym-current-hover-background` | Hover background for current year/month. | +| `$ym-selected-outline-color` | Outline color for selected year/month. | +| `$ym-selected-hover-outline-color` | Hover outline color for selected year/month. | +| `$ym-selected-focus-outline-color` | Focus outline color for selected year/month. | +| `$ym-selected-foreground` | Foreground for selected year/month. Auto-derived from ym-selected-background. | +| `$ym-selected-background` | Background for selected year/month. Auto-derived from header-background. | +| `$ym-selected-hover-foreground` | Hover foreground for selected year/month. | +| `$ym-selected-hover-background` | Hover background for selected year/month. | +| `$ym-selected-current-outline-color` | Outline color for selected current year/month. | +| `$ym-selected-current-outline-hover-color` | Hover outline color for selected current year/month. | +| `$ym-selected-current-outline-focus-color` | Focus outline color for selected current year/month. | +| `$ym-selected-current-foreground` | Foreground for selected current year/month. | +| `$ym-selected-current-background` | Background for selected current year/month. | +| `$ym-selected-current-hover-foreground` | Hover foreground for selected current year/month. | +| `$ym-selected-current-hover-background` | Hover background for selected current year/month. | +| `$week-number-border-radius` | Border radius for week number column. | +| `$week-number-foreground` | Foreground for week number column. Auto-derived from week-number-background. | +| `$week-number-background` | Background for week number column. Auto-derived from content-background. | +| `$content-foreground` | The foreground color for idle dates. Auto-derived from content-background. | +| `$weekend-color` | Color for weekend days. Auto-derived from content-foreground. | +| `$inactive-color` | Color for inactive dates (outside current month). Auto-derived from content-background. | +| `$date-border-radius` | Border radius for date cells. | +| `$date-border-color` | Border color for date cells. | +| `$date-hover-border-color` | Hover border color for date cells. | +| `$date-focus-border-color` | Focus border color for date cells. | +| `$date-hover-background` | Hover background for date cells. Auto-derived from content-background. | +| `$date-focus-background` | Focus background for date cells. Auto-derived from date-hover-background. | +| `$date-hover-foreground` | Hover foreground for date cells. Auto-derived from date-hover-background. | +| `$date-focus-foreground` | Focus foreground for date cells. Auto-derived from date-hover-foreground. | +| `$date-selected-border-color` | Border color for selected date. | +| `$date-selected-hover-border-color` | Hover border color for selected date. | +| `$date-selected-focus-border-color` | Focus border color for selected date. | +| `$date-selected-background` | Background for selected date. Auto-derived from header-background. | +| `$date-selected-foreground` | Foreground for selected date. Auto-derived from date-selected-background. | +| `$date-selected-hover-background` | Hover background for selected date. Auto-derived from date-selected-background. | +| `$date-selected-focus-background` | Focus background for selected date. | +| `$date-selected-hover-foreground` | Hover foreground for selected date. | +| `$date-selected-focus-foreground` | Focus foreground for selected date. | +| `$date-selected-special-border-color` | Border color for selected special date. | +| `$date-selected-special-hover-border-color` | Hover border color for selected special date. | +| `$date-selected-special-focus-border-color` | Focus border color for selected special date. | +| `$date-selected-special-background` | Background for selected special date. | +| `$date-selected-special-foreground` | Foreground for selected special date. | +| `$date-selected-special-hover-background` | Hover background for selected special date. | +| `$date-selected-special-focus-background` | Focus background for selected special date. | +| `$date-selected-special-hover-foreground` | Hover foreground for selected special date. | +| `$date-selected-special-focus-foreground` | Focus foreground for selected special date. | +| `$date-range-border-radius` | Border radius for date range selection. | +| `$date-range-border-color` | Border color for date range selection. | +| `$date-range-preview-border-color` | Preview border color for date range selection. | +| `$date-selected-range-foreground` | Foreground for dates in selected range. | +| `$date-selected-range-background` | Background for dates in selected range. | +| `$date-selected-range-hover-foreground` | Hover foreground for dates in selected range. | +| `$date-selected-range-hover-background` | Hover background for dates in selected range. | +| `$date-selected-range-focus-foreground` | Focus foreground for dates in selected range. | +| `$date-selected-range-focus-background` | Focus background for dates in selected range. | +| `$date-selected-current-range-foreground` | Foreground for current date in selected range. | +| `$date-selected-current-range-background` | Background for current date in selected range. | +| `$date-selected-current-range-hover-foreground` | Hover foreground for current date in selected range. | +| `$date-selected-current-range-hover-background` | Hover background for current date in selected range. | +| `$date-selected-current-range-focus-foreground` | Focus foreground for current date in selected range. | +| `$date-selected-current-range-focus-background` | Focus background for current date in selected range. | +| `$date-current-border-radius` | Border radius for current date. | +| `$date-current-border-color` | Border color for current date. | +| `$date-current-hover-border-color` | Hover border color for current date. | +| `$date-current-focus-border-color` | Focus border color for current date. | +| `$date-current-background` | Background for current date. | +| `$date-current-foreground` | Foreground for current date. | +| `$date-current-hover-background` | Hover background for current date. | +| `$date-current-focus-background` | Focus background for current date. | +| `$date-current-hover-foreground` | Hover foreground for current date. | +| `$date-current-focus-foreground` | Focus foreground for current date. | +| `$date-selected-current-border-color` | Border color for selected current date. | +| `$date-selected-current-hover-border-color` | Hover border color for selected current date. | +| `$date-selected-current-focus-border-color` | Focus border color for selected current date. | +| `$date-selected-current-background` | Background for selected current date. | +| `$date-selected-current-hover-background` | Hover background for selected current date. | +| `$date-selected-current-focus-background` | Focus background for selected current date. | +| `$date-selected-current-foreground` | Foreground for selected current date. | +| `$date-selected-current-hover-foreground` | Hover foreground for selected current date. | +| `$date-selected-current-focus-foreground` | Focus foreground for selected current date. | +| `$date-special-border-radius` | Border radius for special date. | +| `$date-special-border-color` | Border color for special date. | +| `$date-special-hover-border-color` | Hover border color for special date. | +| `$date-special-focus-border-color` | Focus border color for special date. | +| `$date-special-foreground` | Foreground for special date. Auto-derived from header-background. | +| `$date-special-background` | Background for special date. | +| `$date-special-hover-foreground` | Hover foreground for special date. | +| `$date-special-hover-background` | Hover background for special date. | +| `$date-special-focus-foreground` | Focus foreground for special date. | +| `$date-special-focus-background` | Focus background for special date. | +| `$date-special-range-border-color` | Border color for special date in range. | +| `$date-special-range-hover-border-color` | Hover border color for special date in range. | +| `$date-special-range-focus-border-color` | Focus border color for special date in range. | +| `$date-special-range-foreground` | Foreground for special date in range. | +| `$date-special-range-hover-foreground` | Hover foreground for special date in range. | +| `$date-special-range-focus-foreground` | Focus foreground for special date in range. | +| `$date-special-range-background` | Background for special date in range. | +| `$date-special-range-hover-background` | Hover background for special date in range. | +| `$date-special-range-focus-background` | Focus background for special date in range. | +| `$date-disabled-foreground` | Foreground for disabled dates. | +| `$date-disabled-range-foreground` | Foreground for disabled dates in selected range. | + +### Sass Theming + +Import the theming index, where the theme functions and component mixins live: ```scss @use "igniteui-angular/theming" as *; - -// IMPORTANT: Prior to Ignite UI for Angular version 13 use: -// @import '~igniteui-angular/lib/core/styles/themes/index'; ``` -Following the simplest approach, we create a new theme that extends the and by specifying just the `$header-background` and `$content-background` parameters, the theme will automatically compute appropriate state colors and contrast foregrounds. Of course, you're still free to override any of the theme parameters with custom values if needed. +Create a theme that extends . Specifying just `$header-background` and `$content-background` computes the related state colors and contrast foregrounds automatically, and you can still override any parameter: ```scss $custom-calendar-theme: calendar-theme( @@ -658,7 +517,7 @@ $custom-calendar-theme: calendar-theme( ); ``` -The last step is to pass the custom calendar theme: +Pass the custom theme: ```scss :host { @@ -666,13 +525,11 @@ The last step is to pass the custom calendar theme: } ``` - - -### Styling with Tailwind +### Tailwind -You can style the `calendar` using our custom Tailwind utility classes. Make sure to [set up Tailwind](/themes/misc/tailwind-classes) first. +Style the calendar with the custom Tailwind utility classes. First, [set up Tailwind](/themes/misc/tailwind-classes). -Along with the tailwind import in your global stylesheet, you can apply the desired theme utilities as follows: +Along with the Tailwind import in your global stylesheet, add the theme utilities: ```scss @import "tailwindcss"; @@ -680,15 +537,9 @@ Along with the tailwind import in your global stylesheet, you can apply the desi @use 'igniteui-theming/tailwind/utilities/material.css'; ``` -The utility file includes both `light` and `dark` theme variants. - -- Use `light-*` classes for the light theme. -- Use `dark-*` classes for the dark theme. -- Append the component name after the prefix, e.g., `light-calendar`, `dark-calendar`. - -Once applied, these classes enable dynamic theme calculations. From there, you can override the generated CSS variables using `arbitrary properties`. After the colon, provide any valid CSS color format (HEX, CSS variable, RGB, etc.). +The utility file includes both `light` and `dark` variants. Use `light-*` classes for the light theme and `dark-*` classes for the dark theme, appending the component name after the prefix — `light-calendar`, `dark-calendar`. These classes enable dynamic theme calculations, and you override the generated CSS variables using arbitrary properties. After the colon, provide any valid CSS color format (HEX, CSS variable, RGB, etc.). -You can find the full list of properties in the . The syntax is as follows: +Find the full list of properties in the : ```html -The exclamation mark(`!`) is required to ensure the utility class takes precedence. Tailwind applies styles in layers, and without marking these styles as important, they will get overridden by the component’s default theme. +The exclamation mark (`!`) is required so the utility class takes precedence. Tailwind applies styles in layers, and without marking these styles as important they get overridden by the component's default theme. -At the end your calendar should look like this: + - +## Accessibility + +### Keyboard Interaction + +When the calendar is focused, use: + +| Key | Action | +| --- | --- | +| PageUp | Move to the previous month | +| PageDown | Move to the next month | +| Shift + PageUp | Move to the previous year | +| Shift + PageDown | Move to the next year | +| Home | Focus the first day of the month, or the first month/year in view | +| End | Focus the last day of the month, or the last month/year in view | +| Arrow keys | Navigate through days, months, or years in the active view (disabled dates are skipped) | +| Enter / Space | Select the focused day, or open/confirm the focused month or year | + +When the previous or next month button in the subheader is focused, press Space or Enter to scroll the next or previous month into view. When the month button is focused, Space or Enter opens the months view; when the year button is focused, it opens the decade view. + +Day navigation is continuous — arrow keys move through days across month boundaries and change the month in view as needed. + + +Tab navigation reaches these stops: the previous-month button, the month button, the year button, the next-month button, and one date in the grid (the selected date, the current date, or the first focusable date). In multi and range selection, only the first selected date is part of the tab sequence; move between dates in the grid with the arrow keys. + + +### Screen Readers / ARIA + +The calendar view exposes `role="grid"` and tracks the focused cell with `aria-activedescendant`, and sets `aria-multiselectable` when `selection` is `multi` or `range`. The navigation buttons and the month/year pickers expose `role="button"` with localized `aria-label`s, and off-screen live regions announce the presented month and year. All labels come from the calendar resource strings, so they follow the component's `locale` and can be overridden through `resourceStrings`. + +### Accessibility Compliance + +Infragistics evaluates Ignite UI for Angular components against Section 508 and WCAG guidelines — see the [Accessibility Compliance](/interactivity/accessibility-compliance) topic for the full component-by-component matrix. + +| Criterion | How the Calendar complies | +| --- | --- | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html) / [2.1.2 No Keyboard Trap](https://www.w3.org/WAI/WCAG21/Understanding/no-keyboard-trap.html) | Every view (days, months, years) is fully operable from the keyboard — paging, navigation, and selection all have a documented key binding, and arrow-key navigation moves continuously between days without trapping focus. | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) | The view area exposes `role="grid"` with `aria-activedescendant` for the focused cell and `aria-multiselectable` in `multi`/`range` selection; the navigation and picker buttons expose `role="button"` with localized `aria-label`s. | +| [4.1.3 Status Messages](https://www.w3.org/WAI/WCAG21/Understanding/status-messages.html) | Off-screen live regions announce the presented month and year as the user navigates, so the change is available to assistive technology without moving focus. | + +**Your responsibilities** + +- Keep sufficient color contrast between the calendar's background and its date/text colors when customizing the theme — see [Styling](#styling). +- Preserve a logical tab order when embedding the calendar in a custom layout, so the documented Tab stops (navigation buttons, then the grid) stay reachable in sequence. +- If you override `resourceStrings`, keep the replacement labels as descriptive as the defaults they replace. + +## Troubleshooting + +**How do I register the calendar with an `NgModule` instead of the standalone directives?** + +Before standalone components, the calendar was imported through `IgxCalendarModule`. Add it — together with `BrowserAnimationsModule` — to your `AppModule`: + +```typescript +// app.module.ts +import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; +import { IgxCalendarModule } from 'igniteui-angular/calendar'; +// import { IgxCalendarModule } from '@infragistics/igniteui-angular'; for licensed package + +@NgModule({ + imports: [..., BrowserAnimationsModule, IgxCalendarModule], +}) +export class AppModule {} +``` + +Standalone imports (`IGX_CALENDAR_DIRECTIVES` or `IgxCalendarComponent`) are available as of `16.0.0` and are the recommended approach. + +**My Sass `@import` of the theming index no longer resolves.** + +Prior to Ignite UI for Angular version 13, import the themes from the legacy path instead of `@use "igniteui-angular/theming"`: + +```scss +@import '~igniteui-angular/lib/core/styles/themes/index'; +``` + +**Arrow keys don't move focus between days when I press Tab.** + +From version 10.2.0, Tab no longer steps through the days view; use the arrow keys to move between dates. From version 8.2.0, arrow-key navigation does not focus days outside the current month — it changes the month in view instead. ## API References -
+ - - - - -## Additional Resources -
+## Additional Resources Our community is active and always welcoming to new ideas. From 1343bd11b41ee6f69e8186a1a01c38e3ce3f9ee1 Mon Sep 17 00:00:00 2001 From: Ivan Minchev Date: Wed, 15 Jul 2026 17:32:37 +0300 Subject: [PATCH 3/7] docs(ai): update Ignite UI doc topic skill and add adapters --- .ai/skills/igniteui-doc-topics/SKILL.md | 139 ++++++++++++++++++ .../references/audit-rubric.md | 18 ++- .../references/diataxis-cheatsheet.md | 0 .../references/house-style.md | 30 +++- .claude/skills/igniteui-doc-topics/SKILL.md | 139 ++---------------- .codex/skills/igniteui-doc-topics/SKILL.md | 26 ++++ 6 files changed, 220 insertions(+), 132 deletions(-) create mode 100644 .ai/skills/igniteui-doc-topics/SKILL.md rename {.claude => .ai}/skills/igniteui-doc-topics/references/audit-rubric.md (91%) rename {.claude => .ai}/skills/igniteui-doc-topics/references/diataxis-cheatsheet.md (100%) rename {.claude => .ai}/skills/igniteui-doc-topics/references/house-style.md (92%) create mode 100644 .codex/skills/igniteui-doc-topics/SKILL.md diff --git a/.ai/skills/igniteui-doc-topics/SKILL.md b/.ai/skills/igniteui-doc-topics/SKILL.md new file mode 100644 index 0000000000..194c3b30e5 --- /dev/null +++ b/.ai/skills/igniteui-doc-topics/SKILL.md @@ -0,0 +1,139 @@ +--- +name: igniteui-doc-topics +description: >- + Author or audit Ignite UI documentation topics — component pages, how-to guides, conceptual + overviews, and category indexes — for both the Angular doc set and the cross-platform (React / + Web Components / Blazor) doc set. Applies the Diátaxis framework mapped onto Ignite UI's house + templates: canonical section order, fixed heading names, frontmatter (including `llms.description` + and the `relatedComponents` trigger), `.mdx` sample embeds, and per-framework token/PlatformBlock + mechanics. Use this whenever someone asks to write, draft, create, review, audit, fix, or + standardize a documentation topic, tutorial, guide, reference page, or concept overview for Ignite + UI — even if they just say "write docs for the X component" or "review this topic" without naming + Diátaxis or the templates. Also use it when deciding what *kind* of documentation a page should be, + or when a topic mixes tutorial / how-to / reference / explanation content that should be separated. +--- + +# Ignite UI doc topics + +Write and audit Ignite UI documentation topics so every page has the same predictable shape — easy +for developers to read and for AI assistants to answer from. The engine is **Diátaxis** (four +documentation modes) applied through **Ignite UI's house templates**. + +## Two modes of operation + +- **Create** — draft a new topic (component, concept/guide, or category/index) to the standard. +- **Audit** — review an existing topic against the standard and return an issues-and-fixes report. + +Detect which from the request ("write/draft/create" → Create; "review/audit/check/fix/standardize" → +Audit). If a topic file or content is supplied, default to Audit unless they ask for a rewrite. + +## Reference files — load what the task needs + +- `references/diataxis-cheatsheet.md` — the four modes + the compass. Load when classifying a topic + or diagnosing mode-bleed. +- `references/house-style.md` — sections, order, naming, frontmatter, sample/token mechanics, both + doc sets. Load for **every** create or audit. +- `references/audit-rubric.md` — the checkable rules + report format. Load for **every** audit. + +Read `house-style.md` before writing or judging any topic — it carries the mechanical details +(frontmatter fields, ``/`` syntax, Angular-vs-xplat differences) that aren't +in this file. + +## Step 0 — Classify with the compass (always first) + +Before writing or auditing, decide what *kind* of documentation the page is, using the compass from +the cheat-sheet: + +> **action or cognition?** × **acquisition (study) or application (work)?** +> → tutorial · how-to · reference · explanation + +- A **component page** is a *composite* (see below). +- A **concept / guide overview** is **explanation**. +- A **category / index overview** is **reference/navigation** (a map). +- A standalone **"How to …" article** is a **how-to guide** — keep it single-mode. + +If a request is ambiguous ("document X"), state which topic type you're producing and why, in one +line, before proceeding. + +## The composite-topic principle (the heart of this skill) + +Pure Diátaxis says keep the four modes in **separate** documents. Ignite UI **component topics +deliberately don't** — one page carries decision guidance (Overview), a live demo, a how-to +(Getting Started/Usage), do/don't guidance (Best Practices), and reference tables +(Properties/Methods/Events). That is fine **because each *section* owns exactly one mode.** The rule +that makes it work: + +> **One section, one mode. No mode-bleed.** Each section stays in its assigned Diátaxis mode; when a +> second mode wants in, move it to the section that owns it and cross-link. + +Section → mode map (full contents in `house-style.md`): + +| Section | Mode | Stays out of | +|---|---|---| +| Overview: When to Use / When Not to Use | **explanation** | install steps, API detail | +| Live Demo | demonstration (action) | prose/explanation | +| Anatomy: visual + DOM tree / skeleton | orientation (reference) | opinion, install steps | +| Getting Started, Usage | **how-to** | *why* explanations, exhaustive option lists | +| Best Practices: do/don't guidance | **explanation** | install steps, code, API detail | +| Properties / Methods / Events | **reference** | instructions, opinion | +| Styling (`### Sass Theming`, `### Tailwind`, …) | how-to (steps) + reference (tables) | conceptual essays | +| Accessibility | reference (keyboard/ARIA/compliance tables) | tutorials, marketing, unverified conformance claims | +| Troubleshooting | how-to (cause → fix) | background theory | +| API References / Dependencies / Additional Resources | reference / navigation | new teaching | + +Concrete mode-bleed to catch: a *why* paragraph inside **Usage** (→ move to When to Use or a concept +topic, link back); "how to build X" prose inside **Properties** (→ move to Usage; keep the table +descriptive); an exhaustive option list written out in **Usage** prose (→ move to the table). The +cheat-sheet's "two classic confusions" section explains the reasoning. + +## Create workflow + +1. **Classify** (Step 0). Name the topic type. +2. **Pick the doc set & framework.** Angular set = its own file, plain prose. xplat set = one file + for React/WC/Blazor using `{Platform}`/`{ProductName}` tokens and ``. Load + the relevant details from `house-style.md`. +3. **Follow the verification workflow** in `house-style.md` before writing technical content. + Existing snippets and old prose are clues, not authority. +4. **Write frontmatter first** — `title`, `description` (answer-shaped, ≤~160 chars), `keywords`, + `license`, `llms.description`, `mentionedTypes` (xplat), and `relatedComponents` if the component + has close siblings (this lets **Overview**'s **When Not to Use** sub-heading name the specific + sibling instead of speaking generically). +5. **Lay out the canonical sections** in order for that topic type, required ones always present. + Feature-specific content goes as sub-headings under **Usage**, never as new top-level sections. +6. **Fill each section in its mode.** Lead every section with one plain, specific sentence. Put + reference in tables. Embed exactly one top ``, then Usage samples only for distinct tasks + (soft max 5/page). Phrase When-Not-to-Use and Troubleshooting as the reader's real questions. +7. **Self-check against the rubric** before presenting — especially mode-bleed (C-checks) and + metadata (D-checks). Fix, then deliver the `.mdx`. + +## Audit workflow + +1. **Classify** the topic and identify its doc set (Angular vs xplat) and type. +2. **Follow the verification workflow** in `house-style.md` before judging technical content. + Old snippets/prose are never the source of truth by themselves. +3. **Run every check** in `references/audit-rubric.md` — structure/order (A), naming (B), Diátaxis + mode integrity (C), metadata/AI-readiness and correctness (D), samples/links (E), formatting and + snippet currency (F). For mode integrity, run the compass on each section and flag drift. +4. **Report** in the rubric's exact format: Verdict → Summary → Findings (each with Where / Issue / + Principle / Fix) → Quick wins. Order findings Error → Warning → Suggestion. +5. Keep every **Fix** concrete and applyable (the corrected heading, the sentence to move, the table + to add). If the topic is already clean, say so and note what it does well — don't invent problems. + +## Grounding notes + +- The live `vnext` repo is **pre-standardization**: expect drifted headings (`## Angular Rating + Example`, `## Configuration`) and a missing `relatedComponents` field. Author to the **target** + standard; audit against it while recognizing current reality. +- **Invent no verifiable identifier (zero-risk rule).** Never emit a guessed tag, class, package, + property, method, event, CSS part, or theming variable — a plausible-but-wrong name a reader copies is + worse than a visible gap. Use an identifier only when verified (typed API source, an existing topic, + or the user); otherwise write `‹VERIFY: …›`. For Properties/Methods/Events, emit the fixed column + headers plus a build-injection note and leave the rows to the generator. React/Blazor wrapper symbols + resolve to the `igc` core — prefer verified `igc` usage and mark unconfirmed wrapper names `‹VERIFY:…›`. + (Full detail in `house-style.md` → "Never fabricate API identifiers".) +- Prefer paraphrase and the standard section names over copying any existing topic's prose verbatim. +- **Write in one voice and verify every claim** (see house-style → *Voice & tone* and *Verify every + claim against the component*): instruct in the imperative/second person, and check every factual + statement — defaults, behavior, version support, DOM — against the MCP/API-doc source, the official + platform API docs, typed source when needed, or official framework docs before writing it or + recommending it as an edit. Don't "correct" prose into a plausible claim you haven't verified. diff --git a/.claude/skills/igniteui-doc-topics/references/audit-rubric.md b/.ai/skills/igniteui-doc-topics/references/audit-rubric.md similarity index 91% rename from .claude/skills/igniteui-doc-topics/references/audit-rubric.md rename to .ai/skills/igniteui-doc-topics/references/audit-rubric.md index 3dbc1bca03..9ccef9224d 100644 --- a/.claude/skills/igniteui-doc-topics/references/audit-rubric.md +++ b/.ai/skills/igniteui-doc-topics/references/audit-rubric.md @@ -13,7 +13,7 @@ concrete rule below (structure, naming, Diátaxis mode, or metadata) and to a fi ## Checks ### A. Structure & order -- A1 (Error) A required section is missing (Overview, Live Demo, Getting Started, Usage, +- A1 (Error) A required section is missing (Overview, Live Demo, Anatomy, Getting Started, Usage, Best Practices, Properties, Accessibility, API References, Additional Resources on a component topic). - A2 (Warning) Sections are present but out of the canonical order. @@ -26,8 +26,8 @@ concrete rule below (structure, naming, Diátaxis mode, or metadata) and to a fi - A7 (Warning) **When to Use / When Not to Use** are not `###` sub-headings under the `## Overview` section — e.g. they appear as top-level `##`, or are still nested under **Anatomy** (the pre-revision slot). -- A8 (Suggestion) **Anatomy** is missing its opening screenshot/GIF (or a `{/* TODO */}` marker for a - not-yet-available asset), or is missing the DOM tree / skeleton. +- A8 (Warning) **Anatomy** is incomplete: missing its opening screenshot/GIF (or a `{/* TODO */}` + marker for a not-yet-available asset), or missing the verified DOM tree / skeleton. - A9 (Warning) **Accessibility** is missing one of its three required `###` sub-sections — **Keyboard Interaction**, **Screen Readers / ARIA**, **Accessibility Compliance** — or has them out of order. @@ -75,11 +75,17 @@ Run the compass on each section; flag content that has drifted out of the sectio framework-specific content not wrapped in ``. - D8 (Error) An API identifier (tag, class, package, property, method, event, CSS part, theming variable) appears to be fabricated/unverifiable, or an unresolved `‹VERIFY:…›` placeholder was left - in. Reference values must trace to the typed API source. + in. Public API values must trace to the Ignite UI/API docs MCP source, or to the official platform + API docs when MCP is unavailable. - D9 (Error) A **claim** contradicts or isn't verifiable against the component — a wrong default, value range, precedence/fallback behavior, version-support statement, deprecation, or DOM - description. Verify against the typed source / official API (and official framework docs for - version behavior); if unverifiable, don't assert it. + description. For public API facts, verify against the Ignite UI/API docs MCP source first; if MCP is + unavailable, use the official Infragistics API docs for the target platform (React + `https://www.infragistics.com/api/react/`, Web Components + `https://www.infragistics.com/api/webcomponents/`, Blazor + `https://www.infragistics.com/api/blazor`). Use typed source for implementation details not exposed + by API docs, and official framework docs for framework/version behavior; if unverifiable, don't + assert it. Existing topic snippets/prose are not sufficient proof. - D10 (Warning) **Voice/tone drift** — prose isn't imperative/second-person present tense, mixes first-person-plural narration ("we create") with how-to, or carries filler ("simply", "just") or marketing inside instructional prose. diff --git a/.claude/skills/igniteui-doc-topics/references/diataxis-cheatsheet.md b/.ai/skills/igniteui-doc-topics/references/diataxis-cheatsheet.md similarity index 100% rename from .claude/skills/igniteui-doc-topics/references/diataxis-cheatsheet.md rename to .ai/skills/igniteui-doc-topics/references/diataxis-cheatsheet.md diff --git a/.claude/skills/igniteui-doc-topics/references/house-style.md b/.ai/skills/igniteui-doc-topics/references/house-style.md similarity index 92% rename from .claude/skills/igniteui-doc-topics/references/house-style.md rename to .ai/skills/igniteui-doc-topics/references/house-style.md index 484cd57735..b586918746 100644 --- a/.claude/skills/igniteui-doc-topics/references/house-style.md +++ b/.ai/skills/igniteui-doc-topics/references/house-style.md @@ -102,6 +102,30 @@ name that a reader copies is worse than an obvious gap. members through the concrete component instead (`type="Button" member="href"`), and list only the concrete component under **API References**. +## Verification workflow + +Use this checklist when creating technical content or auditing an existing topic. Audit mode reports +verification gaps; it does not edit the topic. Existing topic prose and snippets are evidence to check, +not a source of truth. + +1. **Identify the target platform.** Angular/native `igx`, Web Components `igc`, React, or Blazor. +2. **Verify public API facts through MCP first.** Use the Ignite UI/API docs MCP source for component + types, properties, methods, events, and API-link targets. +3. **If MCP is unavailable, use the official platform API docs.** + - React: `https://www.infragistics.com/api/react/` + - Web Components: `https://www.infragistics.com/api/webcomponents/` + - Blazor: `https://www.infragistics.com/api/blazor` +4. **Use typed source only for details the API docs do not expose.** Examples: rendered DOM, slots, + parts, key handlers, theme `.scss` `@param` comments, precedence rules, and deprecation markers. +5. **Use official framework docs for framework behavior.** Examples: Angular standalone defaults, + control-flow syntax, React conventions, and Blazor conventions. +6. **Mark unresolved facts visibly.** Use `‹VERIFY: exact fact/source needed›` or flag the issue in the + audit report; never replace uncertainty with a plausible claim. + +Authored fenced code snippets follow the same verification order. Live `` embeds are separate: +verify `src`, `alt`, and display props in the topic, but report sample-code problems as upstream sample +project work. + ## Component topic — canonical section order Required = every component topic, always this order. Conditional = only when relevant, but always in @@ -113,7 +137,7 @@ under **Usage**, never a new top-level section. | 1 | *Title + one-line definition* (`#` + lead ¶) | required | orient / reference | H1 is **`‹Component› Component`** — **no** framework prefix, **no** "Overview" suffix (the framework lives in the SEO `title`). Follow with one plain sentence: what it is, what problem it solves. Mirror `llms.description`. | | 2 | **Overview** | required | **explanation** | Introduces the component: its primary purpose, when to reach for it, and the problems it solves, in two sub-headings — **When to Use** and **When Not to Use** (when `relatedComponents` is non-empty, name the better-fit sibling by name and link it; otherwise state the boundary generically). No install steps or API detail here. | | 3 | *Live Demo* | required | demonstration (action) | `` of the simplest useful state, **before** any further prose. | -| 4 | **Anatomy** | conditional (recommended) | orientation (reference) | Opens with a screenshot/GIF of the component's parts or the behavior being shown, then the **DOM tree / skeleton** (rendered elements, parts, slots). If the visual asset doesn't exist yet, leave a `{/* TODO */}` marker rather than a broken image. | +| 4 | **Anatomy** | required for component topics | orientation (reference) | Opens with a screenshot/GIF of the component's parts or the behavior being shown, then the **DOM tree / skeleton** (rendered elements, parts, slots). If the visual asset doesn't exist yet, leave a `{/* TODO */}` marker rather than a broken image, but still include the section and verified skeleton. | | 5 | **Getting Started** | required | how-to | **Lead with the component-specific import/registration** — the page-unique, high-value part. Compress the generic library install to a **single prerequisite line linking the general getting-started topic** (an inline `ng add igniteui-angular` as a parenthetical is fine); **don't** repeat the multi-sentence install boilerplate that is identical on every component page. Show the **current** registration (standalone import) first; put legacy NgModule **after**, marked as legacy. | | 6 | **Usage** | required | how-to | Smallest working snippet per common task; feature specifics are sub-headings here. Sub-headings name the **feature, not the component** (`Shape`, not `Avatar Shape`). Cover **every** public input; state behavioral relationships once (e.g. content-type priority) instead of repeating per option. Styling content belongs in **Styling**, not here. | | 7 | **Best Practices** | required | **explanation** | Practical design recommendations, illustrated with correct-vs-incorrect usage (do/don't pairs). Promotes consistency, usability, and accessibility, and calls out common mistakes. Guidance and examples only — no install steps, no property tables, no accessibility-conformance detail (those stay in their own sections). | @@ -323,7 +347,9 @@ Write instructions the same way across every topic so readers (and assistants) g The zero-risk rule is not limited to identifiers — **every statement of fact must be verified against the actual component before it ships or is recommended as an edit.** This includes defaults, value ranges, precedence/fallback behavior, version support ("since vX"), deprecations, emitted events, and rendered DOM. -- **Source of truth, in order:** the component's typed source (inputs, `@HostBinding`, template, theme `.scss` `@param` comments) → the official generated API docs → an existing verified topic → the user. For framework-version behavior (e.g. Angular standalone defaults), check the **official framework docs**, not memory. +- **Source of truth:** follow the **Verification workflow** above. Public API facts come from MCP + first, then the official platform API docs. Typed source is for implementation details the API docs + do not expose. Existing docs and snippets are never sufficient proof by themselves. - **When recommending edits, verify first.** Never "correct" prose into a plausible-sounding claim you haven't checked — a confident wrong statement is worse than the original. - **If you can't verify it, don't assert it.** Write `‹VERIFY: …›` or leave the existing text and flag it — never guess a default, a version, or a behavior. - Behavioral claims that read fine but contradict the source (e.g. "the image falls back to initials on load error" when the code only sets precedence) are exactly what this rule catches. diff --git a/.claude/skills/igniteui-doc-topics/SKILL.md b/.claude/skills/igniteui-doc-topics/SKILL.md index 976b831ce1..479d47443e 100644 --- a/.claude/skills/igniteui-doc-topics/SKILL.md +++ b/.claude/skills/igniteui-doc-topics/SKILL.md @@ -1,135 +1,26 @@ --- name: igniteui-doc-topics description: >- - Author or audit Ignite UI documentation topics — component pages, how-to guides, conceptual - overviews, and category indexes — for both the Angular doc set and the cross-platform (React / - Web Components / Blazor) doc set. Applies the Diátaxis framework mapped onto Ignite UI's house - templates: canonical section order, fixed heading names, frontmatter (including `llms.description` - and the `relatedComponents` trigger), `.mdx` sample embeds, and per-framework token/PlatformBlock - mechanics. Use this whenever someone asks to write, draft, create, review, audit, fix, or - standardize a documentation topic, tutorial, guide, reference page, or concept overview for Ignite - UI — even if they just say "write docs for the X component" or "review this topic" without naming - Diátaxis or the templates. Also use it when deciding what *kind* of documentation a page should be, - or when a topic mixes tutorial / how-to / reference / explanation content that should be separated. + Author or audit Ignite UI documentation topics: component pages, how-to guides, conceptual + overviews, and category indexes for both the Angular doc set and the cross-platform React / Web + Components / Blazor doc set. Use this whenever someone asks to write, draft, create, review, audit, + fix, or standardize a documentation topic, tutorial, guide, reference page, or concept overview for + Ignite UI. --- -# Ignite UI doc topics +# Ignite UI doc topics adapter -Write and audit Ignite UI documentation topics so every page has the same predictable shape — easy -for developers to read and for AI assistants to answer from. The engine is **Diátaxis** (four -documentation modes) applied through **Ignite UI's house templates**. +This is a Claude adapter for the canonical repo-local skill. -## Two modes of operation +Before doing any task actions, read and follow the canonical skill at: -- **Create** — draft a new topic (component, concept/guide, or category/index) to the standard. -- **Audit** — review an existing topic against the standard and return an issues-and-fixes report. +`../../../.ai/skills/igniteui-doc-topics/SKILL.md` -Detect which from the request ("write/draft/create" → Create; "review/audit/check/fix/standardize" → -Audit). If a topic file or content is supplied, default to Audit unless they ask for a rewrite. +Resolve every canonical reference path relative to that canonical skill directory: -## Reference files — load what the task needs +- `../../../.ai/skills/igniteui-doc-topics/references/diataxis-cheatsheet.md` +- `../../../.ai/skills/igniteui-doc-topics/references/house-style.md` +- `../../../.ai/skills/igniteui-doc-topics/references/audit-rubric.md` -- `references/diataxis-cheatsheet.md` — the four modes + the compass. Load when classifying a topic - or diagnosing mode-bleed. -- `references/house-style.md` — sections, order, naming, frontmatter, sample/token mechanics, both - doc sets. Load for **every** create or audit. -- `references/audit-rubric.md` — the checkable rules + report format. Load for **every** audit. - -Read `house-style.md` before writing or judging any topic — it carries the mechanical details -(frontmatter fields, ``/`` syntax, Angular-vs-xplat differences) that aren't -in this file. - -## Step 0 — Classify with the compass (always first) - -Before writing or auditing, decide what *kind* of documentation the page is, using the compass from -the cheat-sheet: - -> **action or cognition?** × **acquisition (study) or application (work)?** -> → tutorial · how-to · reference · explanation - -- A **component page** is a *composite* (see below). -- A **concept / guide overview** is **explanation**. -- A **category / index overview** is **reference/navigation** (a map). -- A standalone **"How to …" article** is a **how-to guide** — keep it single-mode. - -If a request is ambiguous ("document X"), state which topic type you're producing and why, in one -line, before proceeding. - -## The composite-topic principle (the heart of this skill) - -Pure Diátaxis says keep the four modes in **separate** documents. Ignite UI **component topics -deliberately don't** — one page carries decision guidance (Overview), a live demo, a how-to -(Getting Started/Usage), do/don't guidance (Best Practices), and reference tables -(Properties/Methods/Events). That is fine **because each *section* owns exactly one mode.** The rule -that makes it work: - -> **One section, one mode. No mode-bleed.** Each section stays in its assigned Diátaxis mode; when a -> second mode wants in, move it to the section that owns it and cross-link. - -Section → mode map (full contents in `house-style.md`): - -| Section | Mode | Stays out of | -|---|---|---| -| Overview: When to Use / When Not to Use | **explanation** | install steps, API detail | -| Live Demo | demonstration (action) | prose/explanation | -| Anatomy: visual + DOM tree / skeleton | orientation (reference) | opinion, install steps | -| Getting Started, Usage | **how-to** | *why* explanations, exhaustive option lists | -| Best Practices: do/don't guidance | **explanation** | install steps, code, API detail | -| Properties / Methods / Events | **reference** | instructions, opinion | -| Styling (`### Sass Theming`, `### Tailwind`, …) | how-to (steps) + reference (tables) | conceptual essays | -| Accessibility | reference (keyboard/ARIA/compliance tables) | tutorials, marketing, unverified conformance claims | -| Troubleshooting | how-to (cause → fix) | background theory | -| API References / Dependencies / Additional Resources | reference / navigation | new teaching | - -Concrete mode-bleed to catch: a *why* paragraph inside **Usage** (→ move to When to Use or a concept -topic, link back); "how to build X" prose inside **Properties** (→ move to Usage; keep the table -descriptive); an exhaustive option list written out in **Usage** prose (→ move to the table). The -cheat-sheet's "two classic confusions" section explains the reasoning. - -## Create workflow - -1. **Classify** (Step 0). Name the topic type. -2. **Pick the doc set & framework.** Angular set = its own file, plain prose. xplat set = one file - for React/WC/Blazor using `{Platform}`/`{ProductName}` tokens and ``. Load - the relevant details from `house-style.md`. -3. **Write frontmatter first** — `title`, `description` (answer-shaped, ≤~160 chars), `keywords`, - `license`, `llms.description`, `mentionedTypes` (xplat), and `relatedComponents` if the component - has close siblings (this lets **Overview**'s **When Not to Use** sub-heading name the specific - sibling instead of speaking generically). -4. **Lay out the canonical sections** in order for that topic type, required ones always present. - Feature-specific content goes as sub-headings under **Usage**, never as new top-level sections. -5. **Fill each section in its mode.** Lead every section with one plain, specific sentence. Put - reference in tables. Embed exactly one top ``, then Usage samples only for distinct tasks - (soft max 5/page). Phrase When-Not-to-Use and Troubleshooting as the reader's real questions. -6. **Self-check against the rubric** before presenting — especially mode-bleed (C-checks) and - metadata (D-checks). Fix, then deliver the `.mdx`. - -## Audit workflow - -1. **Classify** the topic and identify its doc set (Angular vs xplat) and type. -2. **Run every check** in `references/audit-rubric.md` — structure/order (A), naming (B), Diátaxis - mode integrity (C), metadata/AI-readiness (D), samples/links (E). For mode integrity, run the - compass on each section and flag drift. -3. **Report** in the rubric's exact format: Verdict → Summary → Findings (each with Where / Issue / - Principle / Fix) → Quick wins. Order findings Error → Warning → Suggestion. -4. Keep every **Fix** concrete and applyable (the corrected heading, the sentence to move, the table - to add). If the topic is already clean, say so and note what it does well — don't invent problems. - -## Grounding notes - -- The live `vnext` repo is **pre-standardization**: expect drifted headings (`## Angular Rating - Example`, `## Configuration`) and a missing `relatedComponents` field. Author to the **target** - standard; audit against it while recognizing current reality. -- **Invent no verifiable identifier (zero-risk rule).** Never emit a guessed tag, class, package, - property, method, event, CSS part, or theming variable — a plausible-but-wrong name a reader copies is - worse than a visible gap. Use an identifier only when verified (typed API source, an existing topic, - or the user); otherwise write `‹VERIFY: …›`. For Properties/Methods/Events, emit the fixed column - headers plus a build-injection note and leave the rows to the generator. React/Blazor wrapper symbols - resolve to the `igc` core — prefer verified `igc` usage and mark unconfirmed wrapper names `‹VERIFY:…›`. - (Full detail in `house-style.md` → "Never fabricate API identifiers".) -- Prefer paraphrase and the standard section names over copying any existing topic's prose verbatim. -- **Write in one voice and verify every claim** (see house-style → *Voice & tone* and *Verify every - claim against the component*): instruct in the imperative/second person, and check every factual - statement — defaults, behavior, version support, DOM — against the component's typed source or the - official API/framework docs before writing it or recommending it as an edit. Don't "correct" prose - into a plausible claim you haven't verified. +Do not treat this adapter as a separate source of rules. If this adapter conflicts with the canonical +skill, the canonical `.ai` skill wins. diff --git a/.codex/skills/igniteui-doc-topics/SKILL.md b/.codex/skills/igniteui-doc-topics/SKILL.md new file mode 100644 index 0000000000..f55d37c3fd --- /dev/null +++ b/.codex/skills/igniteui-doc-topics/SKILL.md @@ -0,0 +1,26 @@ +--- +name: igniteui-doc-topics +description: >- + Author or audit Ignite UI documentation topics: component pages, how-to guides, conceptual + overviews, and category indexes for both the Angular doc set and the cross-platform React / Web + Components / Blazor doc set. Use this whenever someone asks to write, draft, create, review, audit, + fix, or standardize a documentation topic, tutorial, guide, reference page, or concept overview for + Ignite UI. +--- + +# Ignite UI doc topics adapter + +This is a Codex adapter for the canonical repo-local skill. + +Before doing any task actions, read and follow the canonical skill at: + +`../../../.ai/skills/igniteui-doc-topics/SKILL.md` + +Resolve every canonical reference path relative to that canonical skill directory: + +- `../../../.ai/skills/igniteui-doc-topics/references/diataxis-cheatsheet.md` +- `../../../.ai/skills/igniteui-doc-topics/references/house-style.md` +- `../../../.ai/skills/igniteui-doc-topics/references/audit-rubric.md` + +Do not treat this adapter as a separate source of rules. If this adapter conflicts with the canonical +skill, the canonical `.ai` skill wins. From c9c8e182654cd5cc0222c8a962f00288cb3d5ef9 Mon Sep 17 00:00:00 2001 From: Ivan Minchev Date: Fri, 17 Jul 2026 16:58:09 +0300 Subject: [PATCH 4/7] docs(ai): update doc topic skill structure --- .ai/skills/igniteui-doc-topics/SKILL.md | 19 ++--- .../references/audit-rubric.md | 26 +++---- .../references/house-style.md | 72 ++++++++++--------- 3 files changed, 62 insertions(+), 55 deletions(-) diff --git a/.ai/skills/igniteui-doc-topics/SKILL.md b/.ai/skills/igniteui-doc-topics/SKILL.md index 194c3b30e5..30c9dc216f 100644 --- a/.ai/skills/igniteui-doc-topics/SKILL.md +++ b/.ai/skills/igniteui-doc-topics/SKILL.md @@ -58,10 +58,9 @@ line, before proceeding. ## The composite-topic principle (the heart of this skill) Pure Diátaxis says keep the four modes in **separate** documents. Ignite UI **component topics -deliberately don't** — one page carries decision guidance (Overview), a live demo, a how-to -(Getting Started/Usage), do/don't guidance (Best Practices), and reference tables -(Properties/Methods/Events). That is fine **because each *section* owns exactly one mode.** The rule -that makes it work: +deliberately don't** — one page carries a live demo, a how-to (Getting Started/Usage), +decision guidance (Do/Don't), and reference tables (Properties/Methods/Events). That is fine +**because each *section* owns exactly one mode.** The rule that makes it work: > **One section, one mode. No mode-bleed.** Each section stays in its assigned Diátaxis mode; when a > second mode wants in, move it to the section that owns it and cross-link. @@ -70,11 +69,10 @@ Section → mode map (full contents in `house-style.md`): | Section | Mode | Stays out of | |---|---|---| -| Overview: When to Use / When Not to Use | **explanation** | install steps, API detail | | Live Demo | demonstration (action) | prose/explanation | | Anatomy: visual + DOM tree / skeleton | orientation (reference) | opinion, install steps | | Getting Started, Usage | **how-to** | *why* explanations, exhaustive option lists | -| Best Practices: do/don't guidance | **explanation** | install steps, code, API detail | +| Do/Don't: When to Use / When Not to Use | **explanation** | install steps, code, API detail | | Properties / Methods / Events | **reference** | instructions, opinion | | Styling (`### Sass Theming`, `### Tailwind`, …) | how-to (steps) + reference (tables) | conceptual essays | | Accessibility | reference (keyboard/ARIA/compliance tables) | tutorials, marketing, unverified conformance claims | @@ -96,13 +94,16 @@ cheat-sheet's "two classic confusions" section explains the reasoning. Existing snippets and old prose are clues, not authority. 4. **Write frontmatter first** — `title`, `description` (answer-shaped, ≤~160 chars), `keywords`, `license`, `llms.description`, `mentionedTypes` (xplat), and `relatedComponents` if the component - has close siblings (this lets **Overview**'s **When Not to Use** sub-heading name the specific + has close siblings (this lets **Do/Don't**'s **When Not to Use** sub-heading name the specific sibling instead of speaking generically). 5. **Lay out the canonical sections** in order for that topic type, required ones always present. Feature-specific content goes as sub-headings under **Usage**, never as new top-level sections. 6. **Fill each section in its mode.** Lead every section with one plain, specific sentence. Put - reference in tables. Embed exactly one top ``, then Usage samples only for distinct tasks - (soft max 5/page). Phrase When-Not-to-Use and Troubleshooting as the reader's real questions. + reference in tables. In **Usage**, start with a basic declaration and then add property-focused + sub-sections so every public input is shown with a minimal snippet; group only tightly coupled + properties that form one behavior. Embed exactly one top ``, then Usage samples only for + distinct tasks (soft max 5/page). Phrase **Do/Don't** and Troubleshooting as the reader's real + questions. 7. **Self-check against the rubric** before presenting — especially mode-bleed (C-checks) and metadata (D-checks). Fix, then deliver the `.mdx`. diff --git a/.ai/skills/igniteui-doc-topics/references/audit-rubric.md b/.ai/skills/igniteui-doc-topics/references/audit-rubric.md index 9ccef9224d..1ec985096e 100644 --- a/.ai/skills/igniteui-doc-topics/references/audit-rubric.md +++ b/.ai/skills/igniteui-doc-topics/references/audit-rubric.md @@ -13,25 +13,23 @@ concrete rule below (structure, naming, Diátaxis mode, or metadata) and to a fi ## Checks ### A. Structure & order -- A1 (Error) A required section is missing (Overview, Live Demo, Anatomy, Getting Started, Usage, - Best Practices, Properties, Accessibility, API References, Additional Resources on a component +- A1 (Error) A required section is missing (Live Demo, Anatomy, Getting Started, Usage, + Do/Don't, Properties, Accessibility, API References, Additional Resources on a component topic). - A2 (Warning) Sections are present but out of the canonical order. - A3 (Warning) A conditional section sits in the wrong slot. - A4 (Error) A feature-specific top-level `##` exists that should be a sub-heading under **Usage**. -- A5 (Error) **Overview** is not the first section after the title/definition, or **Live Demo** is - missing or doesn't immediately follow **Overview**. +- A5 (Error) **Live Demo** is missing near the top of the topic or appears after **Anatomy**. - A6 (Suggestion) >10 live samples on one page (soft cap) — consider splitting. Up to 10 is fine; only flag when a page clearly sprawls past that. -- A7 (Warning) **When to Use / When Not to Use** are not `###` sub-headings under the `## Overview` - section — e.g. they appear as top-level `##`, or are still nested under **Anatomy** (the - pre-revision slot). +- A7 (Warning) **When to Use / When Not to Use** are not `###` sub-headings under the `## Do/Don't` + section — e.g. they appear as top-level `##`, under **Anatomy**, or under a legacy **Overview** section. - A8 (Warning) **Anatomy** is incomplete: missing its opening screenshot/GIF (or a `{/* TODO */}` marker for a not-yet-available asset), or missing the verified DOM tree / skeleton. - A9 (Warning) **Accessibility** is missing one of its three required `###` sub-sections — **Keyboard Interaction**, **Screen Readers / ARIA**, **Accessibility Compliance** — or has them out of order. -- A10 (Warning) **Best Practices** contains install steps, code snippets, a property table, or other +- A10 (Warning) **Do/Don't** contains install steps, code snippets, a property table, or other reference/how-to content that belongs in Usage, Properties, or Accessibility instead of do/don't guidance. @@ -51,19 +49,21 @@ Run the compass on each section; flag content that has drifted out of the sectio - C2 (Warning) **Instruction inside a reference section** (Properties/Methods/Events telling the reader *how to* build something) — move to Usage; keep the table descriptive. - C3 (Warning) **Reference dumped into Usage** (exhaustive option lists in prose) — move to the table. -- C4 (Warning) **When to Use that only says when to *use*** it, never when *not* to — the +- C4 (Warning) **Do/Don't** only says when to *use* the component, never when *not* to — the When-Not-to-Use redirect is the high-value half. - C5 (Suggestion) Tutorial-style hand-holding in a how-to (or vice-versa) — match the audience. - C6 (Warning) **Styling content inside Usage** (CSS-var overrides, `color`/background snippets) — move to the **Styling** section; Styling should also open with a `` of the result. -- C7 (Warning) **Usage doesn't cover every public input**, or documents each option in isolation - instead of stating the behavioral relationship once (e.g. the content-type priority). -- C8 (Warning) **Best Practices drifts into another mode** — install/code steps (belongs in Getting +- C7 (Warning) **Usage doesn't cover every public input** with a property-focused sub-section and + minimal snippet, omits `### Basic Declaration`, or documents each option in isolation instead of + grouping tightly coupled properties and stating the behavioral relationship once (e.g. the + content-type priority). +- C8 (Warning) **Do/Don't drifts into another mode** — install/code steps (belongs in Getting Started/Usage), an exhaustive option table (belongs in Properties), or conformance claims (belongs in Accessibility) instead of do/don't guidance. ### D. Metadata & AI-readiness -- D1 (Warning) `relatedComponents` is set but **Overview**'s **When Not to Use** doesn't name the +- D1 (Warning) `relatedComponents` is set but **Do/Don't**'s **When Not to Use** doesn't name the specific sibling(s) by name and link them — or vice-versa, it names a sibling that isn't listed in `relatedComponents`. - D2 (Warning) Missing/weak `description` or `llms.description` (not answer-shaped, or >~160 chars). diff --git a/.ai/skills/igniteui-doc-topics/references/house-style.md b/.ai/skills/igniteui-doc-topics/references/house-style.md index b586918746..1ac38a54e4 100644 --- a/.ai/skills/igniteui-doc-topics/references/house-style.md +++ b/.ai/skills/igniteui-doc-topics/references/house-style.md @@ -33,7 +33,7 @@ license: MIT mentionedTypes: ["Rating"] # xplat: API types referenced on the page llms: description: "…" # AI-facing one-liner; the exact text an assistant uses to summarize -relatedComponents: [Toast, Banner] # TARGET field — drives the When to Use trigger (see below) +relatedComponents: [Toast, Banner] # TARGET field — drives the Do/Don't trigger (see below) --- ``` @@ -41,7 +41,7 @@ relatedComponents: [Toast, Banner] # TARGET field — drives the When to Use t self-contained answer sentence. It is *not* optional filler. - **`relatedComponents`** is the revision-2 trigger and is **not yet in the repo**. When authoring to target, set it. When auditing, treat a missing-but-warranted value as a finding, and a set value - with no **When to Use** section as a hard error. + with no **Do/Don't** section and **When Not to Use** sub-section as a hard error. ### MDX imports (declare what you use) @@ -135,28 +135,25 @@ under **Usage**, never a new top-level section. | # | Section (`##`) | Required? | Diátaxis mode | Contents | |---|---|---|---|---| | 1 | *Title + one-line definition* (`#` + lead ¶) | required | orient / reference | H1 is **`‹Component› Component`** — **no** framework prefix, **no** "Overview" suffix (the framework lives in the SEO `title`). Follow with one plain sentence: what it is, what problem it solves. Mirror `llms.description`. | -| 2 | **Overview** | required | **explanation** | Introduces the component: its primary purpose, when to reach for it, and the problems it solves, in two sub-headings — **When to Use** and **When Not to Use** (when `relatedComponents` is non-empty, name the better-fit sibling by name and link it; otherwise state the boundary generically). No install steps or API detail here. | -| 3 | *Live Demo* | required | demonstration (action) | `` of the simplest useful state, **before** any further prose. | -| 4 | **Anatomy** | required for component topics | orientation (reference) | Opens with a screenshot/GIF of the component's parts or the behavior being shown, then the **DOM tree / skeleton** (rendered elements, parts, slots). If the visual asset doesn't exist yet, leave a `{/* TODO */}` marker rather than a broken image, but still include the section and verified skeleton. | -| 5 | **Getting Started** | required | how-to | **Lead with the component-specific import/registration** — the page-unique, high-value part. Compress the generic library install to a **single prerequisite line linking the general getting-started topic** (an inline `ng add igniteui-angular` as a parenthetical is fine); **don't** repeat the multi-sentence install boilerplate that is identical on every component page. Show the **current** registration (standalone import) first; put legacy NgModule **after**, marked as legacy. | -| 6 | **Usage** | required | how-to | Smallest working snippet per common task; feature specifics are sub-headings here. Sub-headings name the **feature, not the component** (`Shape`, not `Avatar Shape`). Cover **every** public input; state behavioral relationships once (e.g. content-type priority) instead of repeating per option. Styling content belongs in **Styling**, not here. | -| 7 | **Best Practices** | required | **explanation** | Practical design recommendations, illustrated with correct-vs-incorrect usage (do/don't pairs). Promotes consistency, usability, and accessibility, and calls out common mistakes. Guidance and examples only — no install steps, no property tables, no accessibility-conformance detail (those stay in their own sections). | -| 8 | **Properties** | required | reference | Table: name · type · default · description. (Replaces "Configuration".) | -| 9 | **Methods** | conditional | reference | Table of callable actions. | -| 10 | **Events** | conditional | reference | Table of emitted events. | -| 11 | **Styling** | required when applicable | how-to + reference | **Open with a `` of the styled result** + one intro line, then the **Styling Variables table** (**one table** — variable · what it changes; **no default-value column, no per-theme tabs**) and styleable-parts table. Subsections cover each approach — **first `### Sass Theming`** (the primary Sass theme workflow), then others (e.g. `### Tailwind`, `### Custom sizing`). All styling content lives here, not under Usage. | -| 12 | **Accessibility** | required | reference | Three sub-sections, in order: **Keyboard Interaction** (key→action table), **Screen Readers / ARIA**, **Accessibility Compliance** (conformance evidence — see the sub-structure spec below). | -| 13 | **Troubleshooting** | conditional (required when version-migration or legacy-setup notes exist) | how-to | Gotchas phrased as the reader's real question; answer as cause → fix. **Collect version-migration notes, deprecations, and legacy/alternative approaches here** — not buried in code-fence comments or scattered asides. | -| 14 | **API References** | required | reference | `` out to the full generated reference; don't duplicate it. | -| 15 | **Dependencies** | conditional | reference | Themes, styles, or supporting components the component relies on to render or function — modules to import (Angular) or supporting components/themes (xplat). (Currently "Theming Dependencies".) | -| 16 | **Additional Resources** | required | navigation | Forums, GitHub, related topics. | - -**When Not to Use trigger:** every component topic carries **Overview** with its **When to Use / When +| 2 | *Live Demo* | required | demonstration (action) | `` of the simplest useful state near the top of the page, before **Anatomy**. | +| 3 | **Anatomy** | required for component topics | orientation (reference) | Opens with a screenshot/GIF of the component's parts or the behavior being shown, then the **DOM tree / skeleton** (rendered elements, parts, slots). If the visual asset doesn't exist yet, leave a `{/* TODO */}` marker rather than a broken image, but still include the section and verified skeleton. | +| 4 | **Getting Started** | required | how-to | **Lead with the component-specific import/registration** — the page-unique, high-value part. Compress the generic library install to a **single prerequisite line linking the general getting-started topic** (an inline `ng add igniteui-angular` as a parenthetical is fine); **don't** repeat the multi-sentence install boilerplate that is identical on every component page. Show the **current** registration (standalone import) first; put legacy NgModule **after**, marked as legacy. | +| 5 | **Usage** | required | how-to | Start with `### Basic Declaration`, showing the smallest valid component markup for each platform. Then add property-focused sub-sections that showcase every public input with a minimal snippet and, when a verified demo exists and adds visual value, a ``. Give standalone properties their own sub-section (`Shape`, not `Avatar Shape`); group only tightly coupled properties that form one behavior (for example, content-source priority such as `src`, `alt`, `initials`, and default slot content). State behavioral relationships once instead of repeating per option. Styling content belongs in **Styling**, not here. | +| 6 | **Do/Don't** | required | **explanation** | Guidance section with **When to Use** and **When Not to Use** sub-sections. Promotes consistency, usability, and accessibility, and calls out better-fit alternatives. Guidance only — no install steps, no code snippets, no property tables, no accessibility-conformance detail (those stay in their own sections). | +| 7 | **Properties** | required | reference | Table: name · type · default · description. (Replaces "Configuration".) | +| 8 | **Methods** | conditional | reference | Table of callable actions. | +| 9 | **Events** | conditional | reference | Table of emitted events. | +| 10 | **Styling** | required when applicable | how-to + reference | **Open with a `` of the styled result** + one intro line, then the **Styling Variables table** (**one table** — variable · what it changes; **no default-value column, no per-theme tabs**) and styleable-parts table. Subsections cover each approach — **first `### Sass Theming`** (the primary Sass theme workflow), then others (e.g. `### Tailwind`, `### Custom sizing`). All styling content lives here, not under Usage. | +| 11 | **Accessibility** | required | reference | Three sub-sections, in order: **Keyboard Interaction** (key→action table), **Screen Readers / ARIA**, **Accessibility Compliance** (conformance evidence — see the sub-structure spec below). | +| 12 | **Troubleshooting** | conditional (required when version-migration or legacy-setup notes exist) | how-to | Gotchas phrased as the reader's real question; answer as cause → fix. **Collect version-migration notes, deprecations, and legacy/alternative approaches here** — not buried in code-fence comments or scattered asides. | +| 13 | **API References** | required | reference | `` out to the full generated reference; don't duplicate it. | +| 14 | **Dependencies** | conditional | reference | Themes, styles, or supporting components the component relies on to render or function — modules to import (Angular) or supporting components/themes (xplat). (Currently "Theming Dependencies".) | +| 15 | **Additional Resources** | required | navigation | Forums, GitHub, related topics. | + +**When Not to Use trigger:** every component topic carries **Do/Don't** with **When to Use / When Not to Use** sub-headings. When `relatedComponents` is non-empty, **When Not to Use** must name the specific better-fit sibling(s) by name and link them; when it's empty (standalone primitives like -Badge/Divider), **When Not to Use** states the boundary without inventing a sibling. (The H2 section -named **Overview** is distinct from the banned "Overview" *suffix* on the H1 title — keep the section, -drop the suffix.) +Badge/Divider), **When Not to Use** states the boundary without inventing a sibling. **Reference-table contract:** Properties / Methods / Events tables are **generated from the same typed API source** as the full reference — not hand-typed. Inline tables = the core knobs for fast scanning; @@ -165,9 +162,17 @@ hand-write or invent rows:** emit the fixed column headers (`name · type · def single build-injection note, and leave the row values to the generator. Inventing a plausible property or event name is exactly the failure this contract exists to prevent. -**Live-sample contract:** exactly one top preview; add Usage samples only for distinct, user-facing -tasks (selection, editing, sorting, validation, templating, styling). Soft max **10 samples/page**; -up to 10 is fine, and only clear sprawl past that warrants splitting into focused topics. +**Usage coverage contract:** begin with `### Basic Declaration`, then use property-focused +sub-sections to demonstrate every public input. Prefer one sub-section per standalone property; group +properties only when they are inseparable in real use or define a shared precedence/behavior. Each +sub-section should include a minimal, copyable snippet for every platform it affects. Add a +`` only when the demo path is verified and the visual result teaches something the snippet +alone does not. + +**Live-sample contract:** exactly one top preview; add Usage samples only for distinct, +user-facing tasks or property-focused behaviors (selection, editing, sorting, validation, +templating, styling, shape, content, sizing). Soft max **10 samples/page**; up to 10 is fine, and +only clear sprawl past that warrants splitting into focused topics. ### `` configuration — pick the props deliberately @@ -245,12 +250,13 @@ mode: statements of fact in tables and short lists — no steps, no marketing. ## Overview topics **5a. Concept / guide overview** (Diátaxis: *explanation*) — e.g. "Theming concepts": -Title + intro → **What You'll Learn** (roadmap) → Concept sections → *Key Capabilities* (cond.) → -*When to Use / When Not to Use* (cond.) → **Next Steps** → **API References / Additional Resources**. +Title + intro → **Overview** → **Before You Start** → **Next Steps** → **Available Tools** → +**Common Workflows** → **Troubleshooting** → **Additional Resources** → optional **FAQ**. Use an +accordion for FAQ content when a compact question-and-answer block is useful. **5b. Category / index overview** (Diátaxis: *reference/navigation* — a map) — e.g. "Charts overview": -Title + intro → **Types / Members** (identical micro-structure per entry: one-line def + link + small -``) → *Key Features* (cond.) → **Next Steps / API References / Additional Resources**. +Title + intro → **Key Features** → **Types** (identical micro-structure per entry: one-line def + link + small +``) → **Next Steps** → **API References / Additional Resources**. Guardrails: cap each section at ~3 short paragraphs (else add sub-sections); isolate marketing copy in a single "Why {ProductName}" section — never thread it through instructional content. @@ -264,12 +270,12 @@ a single "Why {ProductName}" section — never thread it through instructional c | Code Snippet; Examples; "Using the … Component"; "{Platform} X Example"; "Angular X Example" | **Usage** | | "Avatar Shape"; "‹Component› ‹Feature›" (Usage sub-heading) | **`‹Feature›`** (drop the component name) | | Configuration | **Properties** | -| "X vs Y"; "Choosing Between X and Y"; Behavior; Feature Integration | **When to Use** (as `###` under **Overview**) | -| top-level `## When to Use` / `## When Not to Use`; **When to Use / When Not to Use nested under `## Anatomy`** | **`### When to Use` / `### When Not to Use`** nested under **`## Overview`** (first section, before Live Demo) | -| Summary (as lead-in) | intro ¶ or **What You'll Learn** | +| "X vs Y"; "Choosing Between X and Y"; Behavior; Feature Integration | **When to Use** (as `###` under **Do/Don't**) | +| top-level `## When to Use` / `## When Not to Use`; **When to Use / When Not to Use nested under `## Anatomy`** | **`### When to Use` / `### When Not to Use`** nested under **`## Do/Don't`** | +| Summary (as lead-in) | intro ¶ or **Overview** | | Keyboard Navigation | **Accessibility** | | WAI-ARIA Support; Compliance; Section 508; Accessibility Statement | **`### Accessibility Compliance`** (under **Accessibility**) | -| Do's and Don'ts; Guidelines; Recommendations | **Best Practices** | +| Best Practices; Do's and Don'ts; Guidelines; Recommendations | **Do/Don't** | | Theming (H2) | **Styling** (H2); the Sass approach becomes `### Sass Theming` under it | | Known Limitations; Known Issues and Limitations; Limitations | **Troubleshooting** | | API; API Reference (singular) | **API References** | From 19621806b075da4a26196df8c00cd870bf2b7edf Mon Sep 17 00:00:00 2001 From: Ivan Minchev Date: Fri, 17 Jul 2026 17:09:03 +0300 Subject: [PATCH 5/7] fix(docs): lint errors --- docs/angular/src/content/en/components/avatar.mdx | 2 +- docs/angular/src/content/en/components/calendar.mdx | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/angular/src/content/en/components/avatar.mdx b/docs/angular/src/content/en/components/avatar.mdx index f2921cde8f..981ddd15c0 100644 --- a/docs/angular/src/content/en/components/avatar.mdx +++ b/docs/angular/src/content/en/components/avatar.mdx @@ -32,7 +32,7 @@ To display a count, status, or notification indicator rather than represent an e ## Anatomy -{/* TODO: add an anatomy diagram (screenshot or GIF) labeling the avatar's parts. */} +{/*TODO: add an anatomy diagram (screenshot or GIF) labeling the avatar's parts.*/} The avatar is a single host element that renders one content template, chosen by [content priority](#content). Its rendered DOM is: diff --git a/docs/angular/src/content/en/components/calendar.mdx b/docs/angular/src/content/en/components/calendar.mdx index 7c64935b01..251739a53c 100644 --- a/docs/angular/src/content/en/components/calendar.mdx +++ b/docs/angular/src/content/en/components/calendar.mdx @@ -31,7 +31,7 @@ Use the Calendar when you need an always-visible date surface embedded in the pa ## Anatomy -{/* TODO: add an annotated screenshot of the calendar parts (header, navigation subheader, days grid). */} +{/*TODO: add an annotated screenshot of the calendar parts (header, navigation subheader, days grid).*/} The calendar renders a header, a navigation subheader, and a view area that swaps between the days, months, and years views. The header is hidden when `selection` is `multi` or `range`. @@ -326,7 +326,7 @@ public activeViewChanged(event: CalendarView) { ## Properties -{/* Curated core inputs, verified from IgxCalendarComponent. See API References for the complete list. */} +{/*Curated core inputs, verified from IgxCalendarComponent. See API References for the complete list.*/} | Name | Type | Default | Description | | --- | --- | --- | --- | From 173d01f76db9fdd6a64f19a9f0bb42f0c0573635 Mon Sep 17 00:00:00 2001 From: Ivan Minchev Date: Fri, 17 Jul 2026 17:19:12 +0300 Subject: [PATCH 6/7] docs(ai): update usage section --- .ai/skills/igniteui-doc-topics/SKILL.md | 18 ++++---- .../references/audit-rubric.md | 23 +++++----- .../references/house-style.md | 42 +++++++++---------- 3 files changed, 43 insertions(+), 40 deletions(-) diff --git a/.ai/skills/igniteui-doc-topics/SKILL.md b/.ai/skills/igniteui-doc-topics/SKILL.md index 30c9dc216f..92b2996b6d 100644 --- a/.ai/skills/igniteui-doc-topics/SKILL.md +++ b/.ai/skills/igniteui-doc-topics/SKILL.md @@ -59,8 +59,9 @@ line, before proceeding. Pure Diátaxis says keep the four modes in **separate** documents. Ignite UI **component topics deliberately don't** — one page carries a live demo, a how-to (Getting Started/Usage), -decision guidance (Do/Don't), and reference tables (Properties/Methods/Events). That is fine -**because each *section* owns exactly one mode.** The rule that makes it work: +decision guidance in Usage's final Do/Don't subsection, and reference tables +(Properties/Methods/Events). That is fine **because each *section* owns exactly one mode.** The rule +that makes it work: > **One section, one mode. No mode-bleed.** Each section stays in its assigned Diátaxis mode; when a > second mode wants in, move it to the section that owns it and cross-link. @@ -72,14 +73,14 @@ Section → mode map (full contents in `house-style.md`): | Live Demo | demonstration (action) | prose/explanation | | Anatomy: visual + DOM tree / skeleton | orientation (reference) | opinion, install steps | | Getting Started, Usage | **how-to** | *why* explanations, exhaustive option lists | -| Do/Don't: When to Use / When Not to Use | **explanation** | install steps, code, API detail | +| Usage → Do/Don't | **explanation** | install steps, code, API detail | | Properties / Methods / Events | **reference** | instructions, opinion | | Styling (`### Sass Theming`, `### Tailwind`, …) | how-to (steps) + reference (tables) | conceptual essays | | Accessibility | reference (keyboard/ARIA/compliance tables) | tutorials, marketing, unverified conformance claims | | Troubleshooting | how-to (cause → fix) | background theory | | API References / Dependencies / Additional Resources | reference / navigation | new teaching | -Concrete mode-bleed to catch: a *why* paragraph inside **Usage** (→ move to When to Use or a concept +Concrete mode-bleed to catch: a *why* paragraph inside **Usage** (→ move to Do/Don't or a concept topic, link back); "how to build X" prose inside **Properties** (→ move to Usage; keep the table descriptive); an exhaustive option list written out in **Usage** prose (→ move to the table). The cheat-sheet's "two classic confusions" section explains the reasoning. @@ -94,16 +95,17 @@ cheat-sheet's "two classic confusions" section explains the reasoning. Existing snippets and old prose are clues, not authority. 4. **Write frontmatter first** — `title`, `description` (answer-shaped, ≤~160 chars), `keywords`, `license`, `llms.description`, `mentionedTypes` (xplat), and `relatedComponents` if the component - has close siblings (this lets **Do/Don't**'s **When Not to Use** sub-heading name the specific + has close siblings (this lets **Usage**'s final **Do/Don't** subsection name the specific sibling instead of speaking generically). 5. **Lay out the canonical sections** in order for that topic type, required ones always present. Feature-specific content goes as sub-headings under **Usage**, never as new top-level sections. 6. **Fill each section in its mode.** Lead every section with one plain, specific sentence. Put reference in tables. In **Usage**, start with a basic declaration and then add property-focused sub-sections so every public input is shown with a minimal snippet; group only tightly coupled - properties that form one behavior. Embed exactly one top ``, then Usage samples only for - distinct tasks (soft max 5/page). Phrase **Do/Don't** and Troubleshooting as the reader's real - questions. + properties that form one behavior. End **Usage** with `### Do/Don't`, using inline **When to use:** + and **When not to use:** labels rather than nested headings. Embed exactly one top ``, then + Usage samples only for distinct tasks (soft max 5/page). Phrase Do/Don't and Troubleshooting as + the reader's real questions. 7. **Self-check against the rubric** before presenting — especially mode-bleed (C-checks) and metadata (D-checks). Fix, then deliver the `.mdx`. diff --git a/.ai/skills/igniteui-doc-topics/references/audit-rubric.md b/.ai/skills/igniteui-doc-topics/references/audit-rubric.md index 1ec985096e..1d3d2dc93e 100644 --- a/.ai/skills/igniteui-doc-topics/references/audit-rubric.md +++ b/.ai/skills/igniteui-doc-topics/references/audit-rubric.md @@ -14,23 +14,24 @@ concrete rule below (structure, naming, Diátaxis mode, or metadata) and to a fi ### A. Structure & order - A1 (Error) A required section is missing (Live Demo, Anatomy, Getting Started, Usage, - Do/Don't, Properties, Accessibility, API References, Additional Resources on a component + Properties, Accessibility, API References, Additional Resources on a component topic). - A2 (Warning) Sections are present but out of the canonical order. - A3 (Warning) A conditional section sits in the wrong slot. -- A4 (Error) A feature-specific top-level `##` exists that should be a sub-heading under **Usage**. +- A4 (Error) A feature-specific top-level `##` exists that should be a sub-heading under **Usage**, + including a top-level `## Do/Don't`. - A5 (Error) **Live Demo** is missing near the top of the topic or appears after **Anatomy**. - A6 (Suggestion) >10 live samples on one page (soft cap) — consider splitting. Up to 10 is fine; only flag when a page clearly sprawls past that. -- A7 (Warning) **When to Use / When Not to Use** are not `###` sub-headings under the `## Do/Don't` - section — e.g. they appear as top-level `##`, under **Anatomy**, or under a legacy **Overview** section. +- A7 (Warning) **Usage** does not end with `### Do/Don't`, or **When to use:** / **When not to use:** + are written as nested headings instead of inline labels inside that subsection. - A8 (Warning) **Anatomy** is incomplete: missing its opening screenshot/GIF (or a `{/* TODO */}` marker for a not-yet-available asset), or missing the verified DOM tree / skeleton. - A9 (Warning) **Accessibility** is missing one of its three required `###` sub-sections — **Keyboard Interaction**, **Screen Readers / ARIA**, **Accessibility Compliance** — or has them out of order. -- A10 (Warning) **Do/Don't** contains install steps, code snippets, a property table, or other - reference/how-to content that belongs in Usage, Properties, or Accessibility instead of do/don't +- A10 (Warning) **Usage**'s **Do/Don't** subsection contains install steps, code snippets, a property table, or other + reference/how-to content that belongs in Getting Started, another Usage subsection, Properties, or Accessibility instead of do/don't guidance. ### B. Naming @@ -44,12 +45,12 @@ concrete rule below (structure, naming, Diátaxis mode, or metadata) and to a fi ### C. Diátaxis mode integrity (mode-bleed) Run the compass on each section; flag content that has drifted out of the section's assigned mode. -- C1 (Warning) **Explanation inside Usage/Getting Started** ("The reason this works is…") — move to - When to Use / a concept topic and link. +- C1 (Warning) **Explanation inside Usage/Getting Started** outside the final **Do/Don't** subsection + ("The reason this works is…") — move to **Do/Don't** or a concept topic and link. - C2 (Warning) **Instruction inside a reference section** (Properties/Methods/Events telling the reader *how to* build something) — move to Usage; keep the table descriptive. - C3 (Warning) **Reference dumped into Usage** (exhaustive option lists in prose) — move to the table. -- C4 (Warning) **Do/Don't** only says when to *use* the component, never when *not* to — the +- C4 (Warning) **Usage**'s **Do/Don't** only says when to *use* the component, never when *not* to — the When-Not-to-Use redirect is the high-value half. - C5 (Suggestion) Tutorial-style hand-holding in a how-to (or vice-versa) — match the audience. - C6 (Warning) **Styling content inside Usage** (CSS-var overrides, `color`/background @@ -58,12 +59,12 @@ Run the compass on each section; flag content that has drifted out of the sectio minimal snippet, omits `### Basic Declaration`, or documents each option in isolation instead of grouping tightly coupled properties and stating the behavioral relationship once (e.g. the content-type priority). -- C8 (Warning) **Do/Don't drifts into another mode** — install/code steps (belongs in Getting +- C8 (Warning) **Usage**'s **Do/Don't** drifts into another mode — install/code steps (belongs in Getting Started/Usage), an exhaustive option table (belongs in Properties), or conformance claims (belongs in Accessibility) instead of do/don't guidance. ### D. Metadata & AI-readiness -- D1 (Warning) `relatedComponents` is set but **Do/Don't**'s **When Not to Use** doesn't name the +- D1 (Warning) `relatedComponents` is set but **Usage**'s **Do/Don't** guidance doesn't name the specific sibling(s) by name and link them — or vice-versa, it names a sibling that isn't listed in `relatedComponents`. - D2 (Warning) Missing/weak `description` or `llms.description` (not answer-shaped, or >~160 chars). diff --git a/.ai/skills/igniteui-doc-topics/references/house-style.md b/.ai/skills/igniteui-doc-topics/references/house-style.md index 1ac38a54e4..6dcdbdabf6 100644 --- a/.ai/skills/igniteui-doc-topics/references/house-style.md +++ b/.ai/skills/igniteui-doc-topics/references/house-style.md @@ -33,7 +33,7 @@ license: MIT mentionedTypes: ["Rating"] # xplat: API types referenced on the page llms: description: "…" # AI-facing one-liner; the exact text an assistant uses to summarize -relatedComponents: [Toast, Banner] # TARGET field — drives the Do/Don't trigger (see below) +relatedComponents: [Toast, Banner] # TARGET field — drives the Usage Do/Don't trigger (see below) --- ``` @@ -41,7 +41,7 @@ relatedComponents: [Toast, Banner] # TARGET field — drives the Do/Don't trig self-contained answer sentence. It is *not* optional filler. - **`relatedComponents`** is the revision-2 trigger and is **not yet in the repo**. When authoring to target, set it. When auditing, treat a missing-but-warranted value as a finding, and a set value - with no **Do/Don't** section and **When Not to Use** sub-section as a hard error. + with no **Usage** → **Do/Don't** guidance as a hard error. ### MDX imports (declare what you use) @@ -138,22 +138,22 @@ under **Usage**, never a new top-level section. | 2 | *Live Demo* | required | demonstration (action) | `` of the simplest useful state near the top of the page, before **Anatomy**. | | 3 | **Anatomy** | required for component topics | orientation (reference) | Opens with a screenshot/GIF of the component's parts or the behavior being shown, then the **DOM tree / skeleton** (rendered elements, parts, slots). If the visual asset doesn't exist yet, leave a `{/* TODO */}` marker rather than a broken image, but still include the section and verified skeleton. | | 4 | **Getting Started** | required | how-to | **Lead with the component-specific import/registration** — the page-unique, high-value part. Compress the generic library install to a **single prerequisite line linking the general getting-started topic** (an inline `ng add igniteui-angular` as a parenthetical is fine); **don't** repeat the multi-sentence install boilerplate that is identical on every component page. Show the **current** registration (standalone import) first; put legacy NgModule **after**, marked as legacy. | -| 5 | **Usage** | required | how-to | Start with `### Basic Declaration`, showing the smallest valid component markup for each platform. Then add property-focused sub-sections that showcase every public input with a minimal snippet and, when a verified demo exists and adds visual value, a ``. Give standalone properties their own sub-section (`Shape`, not `Avatar Shape`); group only tightly coupled properties that form one behavior (for example, content-source priority such as `src`, `alt`, `initials`, and default slot content). State behavioral relationships once instead of repeating per option. Styling content belongs in **Styling**, not here. | -| 6 | **Do/Don't** | required | **explanation** | Guidance section with **When to Use** and **When Not to Use** sub-sections. Promotes consistency, usability, and accessibility, and calls out better-fit alternatives. Guidance only — no install steps, no code snippets, no property tables, no accessibility-conformance detail (those stay in their own sections). | -| 7 | **Properties** | required | reference | Table: name · type · default · description. (Replaces "Configuration".) | -| 8 | **Methods** | conditional | reference | Table of callable actions. | -| 9 | **Events** | conditional | reference | Table of emitted events. | -| 10 | **Styling** | required when applicable | how-to + reference | **Open with a `` of the styled result** + one intro line, then the **Styling Variables table** (**one table** — variable · what it changes; **no default-value column, no per-theme tabs**) and styleable-parts table. Subsections cover each approach — **first `### Sass Theming`** (the primary Sass theme workflow), then others (e.g. `### Tailwind`, `### Custom sizing`). All styling content lives here, not under Usage. | -| 11 | **Accessibility** | required | reference | Three sub-sections, in order: **Keyboard Interaction** (key→action table), **Screen Readers / ARIA**, **Accessibility Compliance** (conformance evidence — see the sub-structure spec below). | -| 12 | **Troubleshooting** | conditional (required when version-migration or legacy-setup notes exist) | how-to | Gotchas phrased as the reader's real question; answer as cause → fix. **Collect version-migration notes, deprecations, and legacy/alternative approaches here** — not buried in code-fence comments or scattered asides. | -| 13 | **API References** | required | reference | `` out to the full generated reference; don't duplicate it. | -| 14 | **Dependencies** | conditional | reference | Themes, styles, or supporting components the component relies on to render or function — modules to import (Angular) or supporting components/themes (xplat). (Currently "Theming Dependencies".) | -| 15 | **Additional Resources** | required | navigation | Forums, GitHub, related topics. | - -**When Not to Use trigger:** every component topic carries **Do/Don't** with **When to Use / When -Not to Use** sub-headings. When `relatedComponents` is non-empty, **When Not to Use** must name the -specific better-fit sibling(s) by name and link them; when it's empty (standalone primitives like -Badge/Divider), **When Not to Use** states the boundary without inventing a sibling. +| 5 | **Usage** | required | how-to + explanation | Start with `### Basic Declaration`, showing the smallest valid component markup for each platform. Then add property-focused sub-sections that showcase every public input with a minimal snippet and, when a verified demo exists and adds visual value, a ``. Give standalone properties their own sub-section (`Shape`, not `Avatar Shape`); group only tightly coupled properties that form one behavior (for example, content-source priority such as `src`, `alt`, `initials`, and default slot content). The final Usage subsection must be `### Do/Don't`; it uses inline **When to use:** and **When not to use:** labels, not nested headings. Styling content belongs in **Styling**, not here. | +| 6 | **Properties** | required | reference | Table: name · type · default · description. (Replaces "Configuration".) | +| 7 | **Methods** | conditional | reference | Table of callable actions. | +| 8 | **Events** | conditional | reference | Table of emitted events. | +| 9 | **Styling** | required when applicable | how-to + reference | **Open with a `` of the styled result** + one intro line, then the **Styling Variables table** (**one table** — variable · what it changes; **no default-value column, no per-theme tabs**) and styleable-parts table. Subsections cover each approach — **first `### Sass Theming`** (the primary Sass theme workflow), then others (e.g. `### Tailwind`, `### Custom sizing`). All styling content lives here, not under Usage. | +| 10 | **Accessibility** | required | reference | Three sub-sections, in order: **Keyboard Interaction** (key→action table), **Screen Readers / ARIA**, **Accessibility Compliance** (conformance evidence — see the sub-structure spec below). | +| 11 | **Troubleshooting** | conditional (required when version-migration or legacy-setup notes exist) | how-to | Gotchas phrased as the reader's real question; answer as cause → fix. **Collect version-migration notes, deprecations, and legacy/alternative approaches here** — not buried in code-fence comments or scattered asides. | +| 12 | **API References** | required | reference | `` out to the full generated reference; don't duplicate it. | +| 13 | **Dependencies** | conditional | reference | Themes, styles, or supporting components the component relies on to render or function — modules to import (Angular) or supporting components/themes (xplat). (Currently "Theming Dependencies".) | +| 14 | **Additional Resources** | required | navigation | Forums, GitHub, related topics. | + +**When Not to Use trigger:** every component topic ends **Usage** with `### Do/Don't`. This subsection +must include inline **When to use:** and **When not to use:** labels, not nested headings. When +`relatedComponents` is non-empty, **When not to use:** must name the specific better-fit sibling(s) +by name and link them; when it's empty (standalone primitives like Badge/Divider), **When not to +use:** states the boundary without inventing a sibling. **Reference-table contract:** Properties / Methods / Events tables are **generated from the same typed API source** as the full reference — not hand-typed. Inline tables = the core knobs for fast scanning; @@ -270,12 +270,12 @@ a single "Why {ProductName}" section — never thread it through instructional c | Code Snippet; Examples; "Using the … Component"; "{Platform} X Example"; "Angular X Example" | **Usage** | | "Avatar Shape"; "‹Component› ‹Feature›" (Usage sub-heading) | **`‹Feature›`** (drop the component name) | | Configuration | **Properties** | -| "X vs Y"; "Choosing Between X and Y"; Behavior; Feature Integration | **When to Use** (as `###` under **Do/Don't**) | -| top-level `## When to Use` / `## When Not to Use`; **When to Use / When Not to Use nested under `## Anatomy`** | **`### When to Use` / `### When Not to Use`** nested under **`## Do/Don't`** | +| "X vs Y"; "Choosing Between X and Y"; Behavior; Feature Integration | **Do/Don't** (as the final `###` under **Usage**) | +| top-level `## When to Use` / `## When Not to Use`; `### When to Use` / `### When Not to Use`; **When to Use / When Not to Use nested under `## Anatomy`** | Inline **When to use:** / **When not to use:** labels inside the final **Usage** subsection, `### Do/Don't` | | Summary (as lead-in) | intro ¶ or **Overview** | | Keyboard Navigation | **Accessibility** | | WAI-ARIA Support; Compliance; Section 508; Accessibility Statement | **`### Accessibility Compliance`** (under **Accessibility**) | -| Best Practices; Do's and Don'ts; Guidelines; Recommendations | **Do/Don't** | +| Best Practices; Do's and Don'ts; Guidelines; Recommendations | **Do/Don't** (as the final `###` under **Usage**) | | Theming (H2) | **Styling** (H2); the Sass approach becomes `### Sass Theming` under it | | Known Limitations; Known Issues and Limitations; Limitations | **Troubleshooting** | | API; API Reference (singular) | **API References** | From a3db94dc182ae6cbb8516f321e0eb5f01c5f4b15 Mon Sep 17 00:00:00 2001 From: Ivan Minchev Date: Fri, 17 Jul 2026 17:32:41 +0300 Subject: [PATCH 7/7] docs: revert unrelated topic changes --- .../src/content/en/components/avatar.mdx | 306 +++---- .../src/content/en/components/calendar.mdx | 819 ++++++++++-------- 2 files changed, 573 insertions(+), 552 deletions(-) diff --git a/docs/angular/src/content/en/components/avatar.mdx b/docs/angular/src/content/en/components/avatar.mdx index 981ddd15c0..a362e26b4d 100644 --- a/docs/angular/src/content/en/components/avatar.mdx +++ b/docs/angular/src/content/en/components/avatar.mdx @@ -1,214 +1,215 @@ --- title: Angular Avatar Component – Ignite UI for Angular | Infragistics | MIT license -description: The Ignite UI for Angular Avatar is a compact UI element that represents a user or entity with a profile image, an igx-icon, or their initials. +description: Ignite UI for Angular Avatar control enables users to add images, material icons or initials within any application for instances such as a profile button. keywords: Angular Avatar component, Angular Avatar control, Ignite UI for Angular, Angular UI components license: MIT llms: - description: "The Angular Avatar is a compact UI element that represents a user, entity, or object by displaying their profile image, an igx-icon, or their initials." -relatedComponents: [Badge] + description: "Angular Avatar component helps adding initials, images, or material icons to your application." --- import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# Avatar Component +# Angular Avatar Component Overview
-The Angular Avatar is a compact UI element that represents a user, entity, or object by displaying their profile image, an `igx-icon`, or their initials. +Angular Avatar component helps adding initials, images, or material icons to your application.
+ -## Overview +## Angular Avatar Example -### When to Use + -Use the avatar to represent a user, entity, or object with a compact image, icon, or set of initials — for example a profile button, a comment author, or a list item's leading visual. +
-### When Not to Use +## Getting Started with Ignite UI for Angular Avatar -To display a count, status, or notification indicator rather than represent an entity, use the component, which is designed to decorate other elements (including avatars) with a small count or status icon. +To get started with the Ignite UI for Angular Avatar component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: - - -## Anatomy +```cmd +ng add igniteui-angular +``` -{/*TODO: add an anatomy diagram (screenshot or GIF) labeling the avatar's parts.*/} +For a complete introduction to the Ignite UI for Angular, read the [_getting started_](/general/getting-started) topic. -The avatar is a single host element that renders one content template, chosen by [content priority](#content). Its rendered DOM is: +The next step is to import the `IgxAvatarModule` in your **app.module.ts** file. -``` -igx-avatar[role="img"] // host — shape & size set via attributes / CSS vars -└─ one of, by priority: - ├─ div.igx-avatar__image // `src` set — image painted as a background - ├─ igx-icon // `icon` set - ├─ span // `initials` set — first two characters - └─ // custom projected content -``` +```typescript +// app.module.ts -## Getting Started +... +import { IgxAvatarModule } from 'igniteui-angular/avatar'; +// import { IgxAvatarModule } from '@infragistics/igniteui-angular'; for licensed package -Install Ignite UI for Angular first (`ng add igniteui-angular`) — see [Getting Started](/general/getting-started) for the full walkthrough. +@NgModule({ + ... + imports: [..., IgxAvatarModule], + ... +}) +export class AppModule {} +``` -Import the standalone `IgxAvatarComponent` and add it to your component's `imports` array, then use the `` tag in that component's template. +Alternatively, as of `16.0.0` you can import the `IgxAvatarComponent` as a standalone dependency. ```typescript // home.component.ts -import { Component } from '@angular/core'; + +... import { IgxAvatarComponent } from 'igniteui-angular/avatar'; -// Licensed package: import from '@infragistics/igniteui-angular' instead +// import { IgxAvatarComponent } from '@infragistics/igniteui-angular'; for licensed package @Component({ selector: 'app-home', - imports: [IgxAvatarComponent], // makes available in this template - template: '' + template: '', + styleUrls: ['home.component.scss'], + standalone: true, + imports: [IgxAvatarComponent] }) export class HomeComponent {} ``` -## Usage +Now that you have the Ignite UI for Angular Avatar module or component imported, you can start with a basic configuration of the `igx-avatar` component. + +## Using the Angular Avatar Component -The avatar renders initials, an image, or an [`igx-icon`](/icon), in one of three shapes and three preset sizes. +The Ignite UI for Angular Avatar component comes in three shapes (square, rounded, and circle) and three size options (small, medium, and large). It can be used for displaying initials, images or icons. -### Shape +### Avatar Shape -Set the `shape` attribute to `square`, `rounded`, or `circle`. The default is `square`. +We can change the avatar shape through the attribute setting its value to `square`, `rounded` or `circle`. By default, the shape of the avatar is `square`. ```html ``` -### Size +### Avatar displaying initials -Set the `size` attribute to a preset value — `small`, `medium`, or `large` (default `small`). For arbitrary sizes, use the CSS variables described under [Custom sizing](#custom-sizing). +To get a simple avatar with (i.e. JS for 'Jack Sock'), add the following code inside the component template: ```html - + ``` -### Content - -An avatar displays a single kind of content, chosen by **priority**: (image) wins over , which wins over . Set the one you need — a higher-priority value hides the others (this is a precedence rule, not an image load-failure fallback). If none is set, the avatar renders its projected content. - -**Initials** — the first two characters of `initials` are shown (e.g. `JS` for "Jack Sock"): +Let's enhance our avatar by making it circular and bigger in size. ```html - + ``` - +We can also change the background using the `--ig-avatar-background` CSS variable or set a color on the initials through the `color` property. -**Image** — set the image URL via `src`: +```scss +// avatar.component.scss + +igx-avatar { + --ig-avatar-background: #e41c77; + color: #000000; +} -```html - ``` - + +The `roundShape` property of the `igx-avatar` component have been deprecated. The attribute should be used instead. + + +If all went well, you should see something like the following in the browser: + + -**Icon** — render an [`igx-icon`](/icon) by setting its name via `icon`: +### Avatar displaying image + +To get an avatar that displays an image, all you have to do is set the image source via the property. ```html - + + ``` - -The avatar renders icons with the [`igx-icon`](/icon) component. To use Google's Material Icons font, add the following to your `index.html`: `` - - +If all went well, you should see something like the following in the browser: -## Best Practices + -- Pick one content strategy per context and use it consistently — mixing images, icons, and initials in the same list of avatars reads as inconsistent. -- Set only the content you intend to show. `src`, `icon`, and `initials` follow a fixed precedence rather than falling back automatically on failure, so an unreachable image URL won't be replaced by initials — verify the URL if you need a reliable result. -- Set a descriptive `aria-label` whenever the avatar identifies a specific person or entity, not just when it's convenient. -- Don't use the avatar to show a count, status, or notification badge — decorate it with instead of encoding that information into the initials or icon. +### Avatar displaying icon -## Properties +Analogically, the avatar can display an icon via the property. Currently all icons from the material icon set are supported. -The core inputs used to configure the avatar are listed below. For the complete, always-current API surface, see the [API References](#api-references) section. +```html + + +``` -| Property | Type | Default | Description | -| --- | --- | --- | --- | -| `shape` | `"square" \| "rounded" \| "circle"` | `"square"` | Sets the shape of the avatar. | -| `size` | `"small" \| "medium" \| "large"` | `"small"` | Sets the size of the avatar. | -| `initials` | `string` | — | Text initials rendered when no image or icon is set. | -| `icon` | `string` | — | Icon name to render via [`igx-icon`](/icon). | -| `src` | `string` | — | Image source URL to render. | -| `id` | `string` | `"igx-avatar-{n}"` | The unique identifier of the avatar. | + +This component uses Material Icons. Add the following link to your `index.html`: `` + -## Styling +You should see something like this: - + -The avatar's appearance is controlled through the parameters below. Set `$background`, and the contrast-dependent colors (`$color` and `$icon-color`) are derived automatically. +## Styling -| Variable | Description | -| --- | --- | -| `$background` | The avatar background color. Primary token — derives `$color` and `$icon-color`. | -| `$color` | The text/initials color. Auto-derived from `$background` for contrast when not set. | -| `$icon-color` | The icon color. Auto-derived from `$background` for contrast when not set. | -| `$border-radius` | The border radius. Only takes effect when `shape` is `rounded`. | -| `$size` | The size of the avatar. | +### Avatar Theme Property Map -### Sass Theming +Changing the `$background` property automatically updates the following dependent properties: -#### Using SCSS +| Primary Property | Dependent Property | Description | +| --- | --- | --- | +| **$background** | $color | The text color used for the avatar. | +| | $icon-color | The icon color used for the avatar. | -To get started with styling the avatar, import the theme entry point where all the theme functions and component mixins live: +To get started with styling the avatar, we need to import the `index` file, where all the theme functions and component mixins live: ```scss @use "igniteui-angular/theming" as *; + +// IMPORTANT: Prior to Ignite UI for Angular version 13 use: +// @import '~igniteui-angular/lib/core/styles/themes/index'; ``` -Create a new theme that extends the , providing values for the `$background` and `$border-radius` parameters. The `$color` (or `$icon-color`) is automatically set to either black or white, depending on which offers better contrast with the specified background. Note that `$border-radius` only takes effect when the avatar's `shape` is set to `rounded`. +Following the simplest approach, we create a new theme that extends the providing values for the `$background` and `$border-radius` parameters. The `$color` (or `$icon-color`) is automatically set to either black or white, depending on which offers better contrast with the specified background. Note that the `$border-radius` property only takes effect when the avatar's is set to `rounded`. Given the following markup: ```html -
- +
+ +
``` -Create the theme: +We create the following avatar theme: ```scss $custom-avatar-theme: avatar-theme( - $background: #72da67, - $border-radius: 16px + $background: #72da67, + $border-radius: 16px ); ``` -Then apply it to your markup: +The last step is to pass the custom avatar theme: ```scss -.my-container:has(igx-avatar[initials]) { - @include tokens($custom-avatar-theme); +.initials { + @include tokens($custom-avatar-theme); } ``` -#### Using pure CSS +If all went well, you should see something like the following in the browser: -Prefer not to use SCSS? Override the component's CSS variables directly: + -```css -/* overrides all avatars */ -:root { - --ig-avatar-background: #e41c77; -} +### Styling with Tailwind -/* overrides only the avatar with class .special */ -igx-avatar.special { - --background: #e41c77; -} -``` - -### Tailwind - -You can style the avatar using our Tailwind utility classes. Make sure to [set up Tailwind](/themes/misc/tailwind-classes) first. +You can style the `avatar` using our custom Tailwind utility classes. Make sure to [set up Tailwind](/themes/misc/tailwind-classes) first. -With the Tailwind import in your global stylesheet, apply the theme utilities: +Along with the tailwind import in your global stylesheet, you can apply the desired theme utilities as follows: ```scss @import "tailwindcss"; @@ -222,23 +223,25 @@ The utility file includes both `light` and `dark` theme variants. - Use `dark-*` classes for the dark theme. - Append the component name after the prefix, e.g., `light-avatar`, `dark-avatar`. -Once applied, these classes enable dynamic theme calculations. From there, override the generated CSS variables using Tailwind's arbitrary-property syntax — for example `[--background:#FF4E00]` — with any valid CSS color format (HEX, CSS variable, RGB, etc.). +Once applied, these classes enable dynamic theme calculations. From there, you can override the generated CSS variables using `arbitrary properties`. After the colon, provide any valid CSS color format (HEX, CSS variable, RGB, etc.). -See the for the full list of parameters. For example: +You can find the full list of properties in the . The syntax is as follows: ```html +class="!light-avatar ![--background:#FF4E00]" +initials="DY" +shape="rounded"> ``` -The exclamation mark(`!`) is required to ensure the utility class takes precedence. Tailwind applies styles in layers, and without marking these styles as important, they will get overridden by the component's default theme. +The exclamation mark(`!`) is required to ensure the utility class takes precedence. Tailwind applies styles in layers, and without marking these styles as important, they will get overridden by the component’s default theme. - +At the end your avatar should look like this: + + ### Custom sizing @@ -254,6 +257,7 @@ Or you can use the universal `--ig-avatar-size` variable to target all instances ```html
+
``` @@ -264,7 +268,7 @@ Or you can use the universal `--ig-avatar-size` variable to target all instances } ``` -You can also use one of the predefined sizes by assigning it to the `--ig-size` variable, if no `size` attribute is set. The available values for `--ig-size` are `--ig-size-small`, `--ig-size-medium`, and `--ig-size-large`: +You can also use one of the predefined sizes, assigning it to the `--ig-size` variable, if theres no size attribute applied. The available values for `--ig-size` are `--ig-size-small`, `--ig-size-medium`, and `--ig-size-large`: ```scss igx-avatar { @@ -272,80 +276,22 @@ igx-avatar { } ``` -Learn more in the [Size](/display-density) article. - -## Accessibility - -### Keyboard Interaction - -The avatar is a non-interactive, presentational element — it doesn't receive focus and has no keyboard interaction to document. - -### Screen Readers / ARIA - -The avatar renders with `role="img"` and a default `aria-label` of `avatar`, and it automatically sets `aria-roledescription` to reflect its content — `image avatar`, `icon avatar`, `initials avatar`, or `custom avatar` for projected content. - -When the avatar carries meaning — such as identifying a specific person — set a descriptive `aria-label` so screen-reader users get the same information sighted users get from the image, icon, or initials: - -```html - -``` - -If the avatar is purely decorative and its meaning is already conveyed by adjacent text (for example, a name shown next to it), keep the label minimal so the same information isn't announced twice. - -### Accessibility Compliance - -Infragistics evaluates Ignite UI for Angular components against Section 508 and WCAG guidelines — see the [Accessibility Compliance](/interactivity/accessibility-compliance) topic for the full component-by-component matrix. - -| Criterion | How the Avatar complies | -| --- | --- | -| [1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html) | The default `aria-label="avatar"` gives every avatar an accessible name; set your own `aria-label` when the image, icon, or initials convey specific meaning (e.g. a person's identity). | -| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) | The host element exposes `role="img"` and an `aria-roledescription` (`image avatar`, `icon avatar`, `initials avatar`, or `custom avatar`) reflecting its current content. | - -**Your responsibilities** - -- Provide a descriptive `aria-label` whenever the avatar identifies a specific person or entity. -- Keep sufficient color contrast between the avatar's background and its text/icon color when customizing the theme — see [Styling](#styling). - -## Troubleshooting - -### Why doesn't the `roundShape` property work anymore? - -`roundShape` was replaced by `shape` in `15.1.0`. Run `ng update` to migrate existing usages automatically, or update them by hand — `shape="circle"` replaces `roundShape="true"`, and `shape="square"` (the default) replaces `roundShape="false"`. - -### How do I use the avatar in a module-based (NgModule) app? - -Standalone is the default in modern Angular, and Ignite UI for Angular components support it since `16.0.0`. In an older, module-based application, import `IgxAvatarModule` and add it to your `@NgModule` `imports` array instead of importing the component directly: - -```typescript -// app.module.ts -import { IgxAvatarModule } from 'igniteui-angular/avatar'; -// import { IgxAvatarModule } from '@infragistics/igniteui-angular'; for licensed package - -@NgModule({ - imports: [IgxAvatarModule], -}) -export class AppModule {} -``` - -### Why does my theme import fail on older versions? - -The `@use "igniteui-angular/theming" as *;` entry point was introduced in v13. On earlier versions, import the themes index instead: +Learn more about it in the [Size](/display-density) article. -```scss -@import '~igniteui-angular/lib/core/styles/themes/index'; -``` +
## API References - +
- - -## Dependencies +## Theming Dependencies - - ## Additional Resources +
+ Our community is active and always welcoming to new ideas. - [Ignite UI for Angular **Forums**](https://www.infragistics.com/community/forums/f/ignite-ui-for-angular) diff --git a/docs/angular/src/content/en/components/calendar.mdx b/docs/angular/src/content/en/components/calendar.mdx index 127fb35fe1..a89e434a99 100644 --- a/docs/angular/src/content/en/components/calendar.mdx +++ b/docs/angular/src/content/en/components/calendar.mdx @@ -1,9 +1,8 @@ --- -title: Angular Calendar Component – Ignite UI for Angular | MIT license -description: The Angular Calendar component displays dates with single, multiple, or range selection, localization, disabled and special dates, and multiple views. +title: Angular Calendar Component – Ignite UI for Angular | MIT license +description: With Angular Calendar Component, users can create intuitive calendars for applications to display date information using three different selection modes. Try it Now keywords: angular calendar, angular calendar component, angular UI components, angular UI library, ignite ui for angular license: MIT -relatedComponents: [DatePicker, DateRangePicker] llms: description: "Angular Calendar is a UI component used for displaying dates and days in an app." --- @@ -12,47 +11,59 @@ import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro' import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# Calendar Component +# Angular Calendar Component Overview -Angular Calendar is a UI component used for displaying dates and days in an app. It renders a month, year, or decade view and lets users select a single date, multiple dates, or a date range, with support for localization, disabled dates, and special dates. +Angular Calendar is a UI component used for displaying dates and days in an app. Supporting different features, it enables users to easily manage calendar functionalities, drag and create events in a calendar, navigate to a preferred date in it, and show events in an Angular calendar month view, week view, or day view in a single click. -## Overview +
-### When to Use +The Ignite UI for Angular Calendar component, developed as a native [Angular component](https://angular.io/guide/architecture#components), provides an easy and intuitive ways to display date information, enable dates or apply Angular calendar disable dates mode. Users can choose from three different selection modes - single selection, multi selection or range selection. +
-Use the Calendar when you need an always-visible date surface embedded in the page — a scheduling panel, an availability view, or a form that benefits from selecting single dates, multiple dates, or a range directly in the layout. +## Angular Calendar Example -### When Not to Use +We created the following Angular Calendar example using the Ignite UI for Angular Calendar package. It quickly shows how a basic calendar looks and feels like, how users can choose and highlight a single date, and how to move back and forth to a specific date. -- To bind a single date to a text input in a compact dropdown, use the — it hosts a calendar in a drop-down and exposes the value through an input. -- To capture a start/end pair bound to inputs, use the instead of wiring range selection onto a bare calendar. +
- + -## Anatomy +## Getting Started with Ignite UI for Angular Calendar -{/*TODO: add an annotated screenshot of the calendar parts (header, navigation subheader, days grid).*/} +To get started with the Ignite UI for Angular Calendar component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: -The calendar renders a header, a navigation subheader, and a view area that swaps between the days, months, and years views. The header is hidden when `selection` is `multi` or `range`. - -``` -igx-calendar -├── Header // selected date; hidden for multi/range selection -├── Navigation subheader // previous button · month button · year button · next button -└── View area (role="grid") - ├── igx-days-view // day grid for the current month(s) - ├── igx-months-view // month picker - └── igx-years-view // decade (year) picker +```cmd +ng add igniteui-angular ``` -## Getting Started +For a complete introduction to the Ignite UI for Angular, read the [_getting started_](/general/getting-started) topic. -Requires Ignite UI for Angular — see [Getting Started](/general/getting-started) (`ng add igniteui-angular`). +The next step is to import the `IgxCalendarModule` in your **app.module.ts** file. -Import `IGX_CALENDAR_DIRECTIVES` in the component where you use the calendar. The calendar also depends on `BrowserAnimationsModule`, so add it to the same `imports`: + +The also depends on the [`BrowserAnimationsModule`](https://angular.io/api/platform-browser/animations/BrowserAnimationsModule), so it needs to be added to the AppModule as well: + + +```typescript +// app.module.ts +... +import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; +import { IgxCalendarModule } from 'igniteui-angular/calendar'; +// import { IgxCalendarModule } from '@infragistics/igniteui-angular'; for licensed package + +@NgModule({ + ... + imports: [..., BrowserAnimationsModule, IgxCalendarModule], + ... +}) +export class AppModule {} +``` + +Alternatively, as of `16.0.0` you can import the as a standalone dependency, or use the [`IGX_CALENDAR_DIRECTIVES`](https://github.com/IgniteUI/igniteui-angular/blob/master/projects/igniteui-angular/calendar/src/calendar/public_api.ts) token to import the component and all of its supporting components and directives. ```typescript // home.component.ts + import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; import { IGX_CALENDAR_DIRECTIVES } from 'igniteui-angular/calendar'; // import { IGX_CALENDAR_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package @@ -61,66 +72,72 @@ import { IGX_CALENDAR_DIRECTIVES } from 'igniteui-angular/calendar'; selector: 'app-home', template: '', styleUrls: ['home.component.scss'], + standalone: true, imports: [BrowserAnimationsModule, IGX_CALENDAR_DIRECTIVES] + /* or imports: [BrowserAnimationsModule, IgxCalendarComponent] */ }) export class HomeComponent {} ``` -The `IGX_CALENDAR_DIRECTIVES` token imports the together with its views and supporting directives. To register the calendar on its own, import `IgxCalendarComponent` instead. For the legacy `NgModule` setup, see [Troubleshooting](#troubleshooting). +Now that you have the Ignite UI for Angular Calendar module or directives imported, you can start using the `igx-calendar` component. -The uses the [Intl Web API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) for localization and formatting of dates. Consider using [appropriate polyfills](https://github.com/andyearnshaw/Intl.js/) if your target platform does not support them. +The uses the [Intl Web API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) for localization and formatting of dates. +Consider using [appropriate polyfills](https://github.com/andyearnshaw/Intl.js/) if your target platform does not support them. -## Usage +## Using the Angular Calendar -### Single selection +### Angular Single Selection Calendar -Place the `igx-calendar` selector in the template. With no `selection` set, the calendar renders the current month in single selection mode: +Instantiating the is as easy as placing its selector element in the template. This will display the current month in the single selection calendar mode. ```html {/* app.component.html */} +{/* Single selection mode */} ``` -### Multiple selection +### Angular Calendar Multiselect -Set the property to `multi` to let users pick several individual dates: +We can easily change the default mode using the property: ```html {/* app.component.html */} +{/* Multi selection mode */} ``` - + -### Range selection +### Angular Calendar Range Picker -Set `selection` to `range` to let users pick a continuous range between two dates: +Following the same approach, we can switch to range selection mode: ```html {/* app.component.html */} +{/* Range selection mode */} ``` - + -The calendar header is not rendered when `selection` is either `multi` or `range`. +Notice that the calendar header is not rendered when the selection is either `multi` or `range`. -### Localization and formatting +### Localization and Formatting -Control localization and formatting through , , , and . +Due to their very nature, localization and formatting are essential to any calendar. In the those are controlled and customized through the following properties - , , , . -`weekStart` sets the starting day of the week. If you don't set it, the calendar uses the first day of the week for its `locale`. Set it to `1` for Monday. `formatOptions` and `formatViews` customize how the day, month, and year are rendered, and `locale` sets the language: +Let's go ahead and try those along with other customizations from the API. First thing we need to set is the , which controls the starting day of the week. It defaults to 0, which corresponds to Sunday, so we will set a value of 1 for Monday. In the markup below we are also binding the `formatOptions` and properties to customize the display formatting. Finally, we are binding the `locale` property to a value, based on the user's location choice: ```html {/* app.component.html */} - @for (locale of locales; track locale) { - {{ locale }} - } + + {{ locale }} + +If everything went well, we should now have a calendar with customized dates display, that also changes the locale representation, based on the user location. Let's have a look at it: + + -### Disabled dates +### How to Disable Dates In Angular Calendar -Assign an array of descriptors to to prevent dates from being selected. Use to describe the range to disable. +This section demonstrates the usage of functionality. For this purpose, different single dates or ranges can be added to an array and then passed to the descriptor. -Disable the dates between the 3rd and the 8th of the current month: +The is used to specify a range that is going to be disabled. + +Let's create a sample that is disabling the dates between the 3rd and the 8th of the current month: ```typescript export class CalendarSample6Component { @@ -171,11 +192,15 @@ export class CalendarSample6Component { } ``` - +These configurations should have the following result: + + ### Special dates - uses the same descriptor configuration as `disabledDates`, but special dates stay selectable and focusable. Create a of type and pass an array of dates as its : +The feature is using almost the same configuration principles as the . The ability to select and focus is what differs them from the `disabled` ones. + +Let's add some to our `igxCalendar`. In order to do this, we have to create a item of type and pass an array of dates as a : ```typescript export class CalendarSample7Component { @@ -214,44 +239,165 @@ export class CalendarSample7Component { ``` - +The following demo illustrates a calendar with a vacation request option: + + ### Week numbers -Set to `true` to display week numbers. The same input applies to the Date Picker. +You can now use input to show the week numbers for both Calendar and DatePicker components. ```html + {/* app.component.html */} ``` - +The following demo illustrates a calendar with enabled week numbers: + + + +## Calendar Events + +Let's explore the events emitted by the calendar: + +- - emitted when selecting date(s) in the calendar. +- - emitted every time when the presented month/year is changed - for example after navigating to the `next` or `previous` month. +- - emitted after the active view is changed - for example after the user has clicked on the `month` or `year` section in the header. + +```html +{/* app.component.html */} + + +``` + +The event is suitable to build input validation logic. Use the code from below to alert the user if selection exceeds 5 days, and then reset the selection: + +```typescript +// app.component.ts +... +public onSelection(dates: Date[]) { + if (dates.length > 5) { + this.calendar.selectedDates = []; + // alert the user + } +} +public viewDateChanged(event: IViewDateChangeEventArgs) { + // use event.previousValue to get previous month/year that was presented. + // use event.currentValue to get current month/year that is presented. +} + +public activeViewChanged(event: CalendarView) { + // use CalendarView[event] to get the current active view (DEFAULT, YEAR or DECADE) +} +``` + +Use the demo below to play around (change selection, navigate through months and years) and see the events logged real time: + + + +## Angular Calendar Views + +There are separate views provided by the `IgxCalendarModule` that can be used independently: + +- Angular Calendar Days View - + + -### Views +- Angular Calendar Month View - -The days, months, and years views ship as standalone components you can use independently of the full calendar: + -- — the day grid. +- Angular Calendar Year View - - + -- — the month picker. +## Keyboard navigation - +If you traverse the page using _Tab key_ you should keep in mind that based on [W3 accessibility recommendations](https://www.w3.org/TR/wai-aria-practices/#layoutGrid) the now introduces the following tab stops: -- — the year picker. +- Previous month button +- Month selection button +- Year selection button +- Next month button +- Selected date, Current date, First focusable (not disabled) date in the days view + +In an Angular Calendar that contains more than one selected dates, only the first date will be introduced as a tab stop. For example, when an Angular Calendar multi-select is enabled and you have selected the dates: _13/10/2020_, _17/10/2020_ and _21/10/2020_ only _13/10/2020_ will be accessible during tab navigation; in an Angular Calendar Range Picker, only the first date of the selected range will be part of the _page tab sequence_. + + +Behavioral change, from _v10.2.0_ - Tab key navigation in the _days view_ is no longer available. In order to navigate between the dates in the _date view_ you should use the _arrow keys_. + + +When the `igxCalendar` component is focused, use: + +- PageUp key to move to the previous month, +- PageDown key to move to the next month, +- Shift + PageUp keys to move to the previous year, +- Shift + PageDown keys to move to the next year, +- Home key to focus the first day of the current month or first month in view +- End key to focus the last day of the current month or last month in view + +When the `prev` or the `next` month buttons (in the subheader) are focused, use: + +- Space or Enter key to scroll into view the next or previous month. + +When the `months` button (in the subheader) is focused, use: + +- Space or Enter key to open the months view. + +When the `year` button (in the subheader) is focused, use: + +- Space or Enter key to open the decade view. + +When a `day` inside the current month is focused: + +- Use _Arrow keys_ to navigate through the days. Note: The disabled dates will be skipped. +- Focus will be persisted on the current month that is in the view, while navigation **from**/**to** the **last day**/**first day** of the month. +- THe kb navigation would be continuous, which means that it will go through all months while navigating with the arrows. +- Use Enter key to select the currently focused day. + +When a `month` inside the months view is focused, use: + +- Arrow keys to navigate through the months. +- Home key to focus the first month inside the months view. +- End key to focus the last month inside the months view. +- Enter key to select the currently focused month and close the view. + +When an `year` inside the decade view is focused, use: + +- Arrow up and Arrow down keys to navigate through the years, +- Enter key to select the currently focused year and close the view. + + +Following version 8.2.0, keyboard navigation will not focus days that are outside of current month, but will rather change the month in view. + - +## Multi View Calendar -### Multi-view +Multi-view calendar supports all three types of selection. Use the input to set the number of displayed months, which will be shown horizontally in a flex container. There is no limit on the max value set. While using a multi view calendar, you may want to hide the days that do not belong to the current month. You are able to do it with the property. Keyboard navigation moves to next/previous months when those are in view. -Set to render several months side by side in a flex container; multi-view supports all three selection types. There is no maximum value. Set to `true` to hide days that don't belong to the current month, and keyboard navigation moves to the next or previous month when it is in view. + - +## Calendar Orientation -### Orientation +The orientation settings allows users to choose how the header and the view of the calendar are displayed. -Set `headerOrientation` to place the header `horizontal` (above the view) or `vertical` (beside the view). Set `orientation` to lay the months out `horizontal` (side by side) or `vertical` (stacked). Both default to `horizontal`. +### Header Orientation Options + +You can change the header orientation to place the header of the calendar to be either horizontal(above the calendar view) or vertical(on the side of the calendar view). +To do that, use the property, setting it respectively to `horizontal` or `vertical` + +### View Orientation Options + +You can set the view orientation to place the months in the calendar either horizontally(side by side) or vertically(above one another). +To do that, use the property, setting it respectively to `horizontal` or `vertical`. + + +You need at least two month view calendar to see that property working. + ```html @@ -276,239 +422,234 @@ export class CalendarSample9Component { } ``` - -Set `monthsViewNumber` to at least `2` to see the `orientation` setting take effect. - + - +## Styling -### Handling events +### Calendar Theme Property Map -Bind to the calendar events to react to selection and navigation: +When you modify the `$header-background` and `$content-background` properties, all related theme properties are automatically adjusted to ensure your calendar component is styled consistently. See the tables below for a detailed overview of which theme properties are affected. -```html -{/* app.component.html */} - - -``` +
-The event emits a single `Date` in `single` selection and a `Date[]` in `multi` or `range` selection, so it is a good place for validation. Alert the user when the selection exceeds 5 days and then reset it: +{/*Theme Switcher Radios and Labels*/} + + + + + + + + -```typescript -// app.component.ts -public onSelection(dates: Date[]) { - if (dates.length > 5) { - this.calendar.selectedDates = []; - // alert the user - } -} -public viewDateChanged(event: IViewDateChangeEventArgs) { - // use event.previousValue to get the previously presented month/year. - // use event.currentValue to get the currently presented month/year. -} +
-public activeViewChanged(event: CalendarView) { - // use CalendarView[event] to get the current active view (DEFAULT, YEAR or DECADE) -} -``` + {/* Material Theme Table */} +
- - -## Best Practices - -- Match the `selection` mode to the real task — `single` for one date, `multi` for scattered individual picks, `range` for a start/end pair — instead of layering custom logic onto the wrong mode. -- Use `disabledDates` and `specialDates` to communicate availability directly in the grid rather than relying on separate legend text the user has to cross-reference. -- Set `weekStart` and `locale` together when localizing — leaving `weekStart` unset lets the calendar infer it from `locale`, so setting one without the other can produce a week layout that doesn't match the surrounding page's language. -- Don't embed a full Calendar just to capture one date bound to a text field — use the Date Picker instead (see [When Not to Use](#when-not-to-use)). - -## Properties - -{/*Curated core inputs, verified from IgxCalendarComponent. See API References for the complete list.*/} - -| Name | Type | Default | Description | -| --- | --- | --- | --- | -| `selection` | `'single' \| 'multi' \| 'range'` | `'single'` | Selection mode. Changing it resets the current selection. | -| `value` | `Date \| Date[]` | — | Selected date(s): a single `Date` for `single`, otherwise a `Date[]`. | -| `viewDate` | `Date` | current date | The date presented when the calendar renders. | -| `weekStart` | `WEEKDAYS \| number` | locale's first day | Starting day of the week; falls back to the `locale`'s first day. | -| `locale` | `string` | application locale | BCP 47 language tag used for formatting. | -| `formatOptions` | `IFormattingOptions` | `{ day: 'numeric', month: 'long', weekday: 'narrow', year: 'numeric' }` | `Intl` date-format options per view. | -| `formatViews` | `IFormattingViews` | `{ day: false, month: true, year: false }` | Which views apply `formatOptions`. | -| `disabledDates` | `DateRangeDescriptor[]` | `[]` | Ranges that cannot be selected. | -| `specialDates` | `DateRangeDescriptor[]` | `[]` | Highlighted ranges that remain selectable. | -| `showWeekNumbers` | `boolean` | `false` | Displays the week numbers column. | -| `hideOutsideDays` | `boolean` | `false` | Hides days that fall outside the current month. | -| `monthsViewNumber` | `number` | `1` | Number of month views rendered side by side. | -| `hasHeader` | `boolean` | `true` | Renders the calendar header (single selection only). | -| `headerOrientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Header placement relative to the view. | -| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction of the month views. | -| `activeView` | `IgxCalendarView` | `'month'` | The view in focus (`month`, `year`, or `decade`). | - -## Methods - -| Name | Parameters | Description | + | Primary Property | Dependent Property | Description | | --- | --- | --- | -| `selectDate` | `value: Date \| Date[] \| string` | Selects date(s) according to the current `selection` mode. | -| `deselectDate` | `value?: Date \| Date[] \| string` | Deselects date(s); clears the whole selection when called with no argument. | - -## Events - -| Name | Type | Description | +| **$header-background** | $header-foreground | Text color for the calendar header | +| | $picker-hover-foreground | Picker hover foreground | +| | $picker-focus-foreground | Picker focus foreground | +| | $navigation-hover-color | Hover color for navigation | +| | $navigation-focus-color | Focus color for navigation | +| | $date-selected-background | Background for selected dates | +| | $date-selected-current-background | Selected current date background | +| | $date-selected-foreground | Foreground for selected dates | +| | $date-selected-current-foreground | Foreground for selected current date | +| | $date-selected-current-border-color | Border color for selected current date | +| | $date-selected-special-border-color | Border color for selected special dates | +| | $ym-selected-background | Year/month selected background | +| | $ym-selected-hover-background | Hover background for year/month selected date | +| | $ym-selected-current-background | Current selected year/month background | +| | $ym-selected-current-hover-background | Hover background for current selected year/month | +| | $ym-selected-foreground | Foreground for selected year/month | +| | $ym-selected-hover-foreground | Hover foreground for selected year/month | +| | $ym-selected-current-foreground | Foreground for current selected year/month | +| | $ym-selected-current-hover-foreground | Hover foreground for current selected year/month | +| **$content-background** | $content-foreground | Text and icon color inside calendar content area | +| | $weekend-color | Color for weekend dates | +| | $inactive-color | Color for dates outside active range | +| | $weekday-color | Color for weekday labels | +| | $picker-background | Picker background | +| | $date-hover-background | Background for hovered dates | +| | $date-hover-foreground | Foreground for hovered dates | +| | $date-focus-background | Background for focused dates | +| | $date-focus-foreground | Foreground for focused dates | +| | $date-current-background | Background for the current date | +| | $date-current-foreground | Foreground for the current date | +| | $date-current-border-color | Border color for the current date | +| | $ym-current-background | Year/month current background | +| | $ym-current-hover-background | Hover background for current year/month | +| | $ym-current-foreground | Foreground for current year/month | +| | $ym-current-hover-foreground | Hover foreground for current year/month | +| | $date-selected-range-background | Selected range background | +| | $date-selected-range-foreground | Foreground for selected date ranges | +| | $date-selected-current-range-background | Background for selected current date ranges | +| | $date-selected-current-range-hover-background | Hover background for selected current date ranges | +| | $date-selected-current-range-focus-background | Focus background for selected current date ranges | +| | $date-selected-current-range-foreground | Foreground for selected current date ranges | +| | $date-special-foreground | Foreground for special dates | +| | $date-special-border-color | Border color for special dates | +| | $date-special-hover-border-color | Hover border color for special dates | +| | $date-special-focus-foreground | Focus foreground for special dates | +| | $date-special-range-foreground | Foreground for special date ranges | +| | $date-special-range-border-color | Border color for special date ranges | +| | $date-special-range-hover-background | Hover background for special date ranges | +| | $date-selected-special-border-color | Border color for selected special dates | +| | $date-selected-special-hover-border-color | Hover border color for selected special dates | +| | $date-selected-special-focus-border-color | Focus border color for selected special dates | +| | $date-disabled-foreground | Foreground for disabled dates | +| | $date-disabled-range-foreground | Foreground for disabled ranges | +| **$date-border-radius** | $date-range-border-radius | Controls the border radius for date ranges. | +| | $date-current-border-radius | Controls the border radius for the current date. | +| | $date-special-border-radius | Controls the border radius for special dates. | +| | $date-border-radius | If not specified and `$date-range-border-radius` is set, uses the value of `$date-range-border-radius`. | + +
+ {/* Fluent Theme Table */} +
+ + | Primary Property | Dependent Property | Description | | --- | --- | --- | -| `selected` | `EventEmitter` | Emitted when date(s) are selected. | -| `viewDateChanged` | `EventEmitter` | Emitted when the presented month or year changes. | -| `activeViewChanged` | `EventEmitter` | Emitted when the active view changes (for example, from month to year). | - -## Styling - -Style the calendar by creating a theme and passing it to the component. The sample below applies a custom `$header-background` and `$content-background`: - - - -All themes expose the same set of variables — only their default values differ per theme. Many of them auto-derive from the primary properties (`$header-background`, `$content-background`) when not set explicitly, so the component stays visually consistent. - -| Variable | Description | -| --- | --- | -| `$size` | Size of days, months, and years views. | -| `$inner-size` | Inner size for calendar elements. | -| `$weekday-color` | Color for weekday labels. Auto-derived from content-background. | -| `$actions-divider-color` | Divider color for date-picker actions. | -| `$border-radius` | Border radius for calendar container. | -| `$content-background` | Background color for calendar. PRIMARY - derives content-foreground, inactive-color, date-hover colors, week-number colors. | -| `$border-color` | Border color for calendar container. | -| `$header-background` | Header background color. PRIMARY - derives header-foreground and most accent/selection colors. | -| `$header-foreground` | Header foreground color. Auto-derived from header-background. | -| `$picker-foreground` | Foreground for the calendar picker. Auto-derived from picker-background. | -| `$picker-background` | Background for the calendar picker. | -| `$picker-hover-foreground` | Hover foreground for the calendar picker. Auto-derived from header-background. | -| `$picker-focus-foreground` | Focus foreground for the calendar picker. Auto-derived from picker-hover-foreground. | -| `$navigation-color` | Icon color for month navigation. Auto-derived from picker-background. | -| `$navigation-hover-color` | Hover color for navigation icons. Auto-derived from picker-hover-foreground. | -| `$navigation-focus-color` | Focus color for navigation icons. Auto-derived from navigation-hover-color. | -| `$ym-border-radius` | Border radius for year/month views. | -| `$ym-hover-foreground` | Hover foreground for year/month. Auto-derived from ym-hover-background. | -| `$ym-hover-background` | Hover background for year/month. Auto-derived from date-hover-background. | -| `$ym-current-outline-color` | Outline color for current year/month. Auto-derived from date-current-border-color. | -| `$ym-current-outline-hover-color` | Hover outline color for current year/month. | -| `$ym-current-outline-focus-color` | Focus outline color for current year/month. | -| `$ym-current-background` | Background for current year/month. | -| `$ym-current-foreground` | Foreground for current year/month. Auto-derived from ym-current-background. | -| `$ym-current-hover-foreground` | Hover foreground for current year/month. | -| `$ym-current-hover-background` | Hover background for current year/month. | -| `$ym-selected-outline-color` | Outline color for selected year/month. | -| `$ym-selected-hover-outline-color` | Hover outline color for selected year/month. | -| `$ym-selected-focus-outline-color` | Focus outline color for selected year/month. | -| `$ym-selected-foreground` | Foreground for selected year/month. Auto-derived from ym-selected-background. | -| `$ym-selected-background` | Background for selected year/month. Auto-derived from header-background. | -| `$ym-selected-hover-foreground` | Hover foreground for selected year/month. | -| `$ym-selected-hover-background` | Hover background for selected year/month. | -| `$ym-selected-current-outline-color` | Outline color for selected current year/month. | -| `$ym-selected-current-outline-hover-color` | Hover outline color for selected current year/month. | -| `$ym-selected-current-outline-focus-color` | Focus outline color for selected current year/month. | -| `$ym-selected-current-foreground` | Foreground for selected current year/month. | -| `$ym-selected-current-background` | Background for selected current year/month. | -| `$ym-selected-current-hover-foreground` | Hover foreground for selected current year/month. | -| `$ym-selected-current-hover-background` | Hover background for selected current year/month. | -| `$week-number-border-radius` | Border radius for week number column. | -| `$week-number-foreground` | Foreground for week number column. Auto-derived from week-number-background. | -| `$week-number-background` | Background for week number column. Auto-derived from content-background. | -| `$content-foreground` | The foreground color for idle dates. Auto-derived from content-background. | -| `$weekend-color` | Color for weekend days. Auto-derived from content-foreground. | -| `$inactive-color` | Color for inactive dates (outside current month). Auto-derived from content-background. | -| `$date-border-radius` | Border radius for date cells. | -| `$date-border-color` | Border color for date cells. | -| `$date-hover-border-color` | Hover border color for date cells. | -| `$date-focus-border-color` | Focus border color for date cells. | -| `$date-hover-background` | Hover background for date cells. Auto-derived from content-background. | -| `$date-focus-background` | Focus background for date cells. Auto-derived from date-hover-background. | -| `$date-hover-foreground` | Hover foreground for date cells. Auto-derived from date-hover-background. | -| `$date-focus-foreground` | Focus foreground for date cells. Auto-derived from date-hover-foreground. | -| `$date-selected-border-color` | Border color for selected date. | -| `$date-selected-hover-border-color` | Hover border color for selected date. | -| `$date-selected-focus-border-color` | Focus border color for selected date. | -| `$date-selected-background` | Background for selected date. Auto-derived from header-background. | -| `$date-selected-foreground` | Foreground for selected date. Auto-derived from date-selected-background. | -| `$date-selected-hover-background` | Hover background for selected date. Auto-derived from date-selected-background. | -| `$date-selected-focus-background` | Focus background for selected date. | -| `$date-selected-hover-foreground` | Hover foreground for selected date. | -| `$date-selected-focus-foreground` | Focus foreground for selected date. | -| `$date-selected-special-border-color` | Border color for selected special date. | -| `$date-selected-special-hover-border-color` | Hover border color for selected special date. | -| `$date-selected-special-focus-border-color` | Focus border color for selected special date. | -| `$date-selected-special-background` | Background for selected special date. | -| `$date-selected-special-foreground` | Foreground for selected special date. | -| `$date-selected-special-hover-background` | Hover background for selected special date. | -| `$date-selected-special-focus-background` | Focus background for selected special date. | -| `$date-selected-special-hover-foreground` | Hover foreground for selected special date. | -| `$date-selected-special-focus-foreground` | Focus foreground for selected special date. | -| `$date-range-border-radius` | Border radius for date range selection. | -| `$date-range-border-color` | Border color for date range selection. | -| `$date-range-preview-border-color` | Preview border color for date range selection. | -| `$date-selected-range-foreground` | Foreground for dates in selected range. | -| `$date-selected-range-background` | Background for dates in selected range. | -| `$date-selected-range-hover-foreground` | Hover foreground for dates in selected range. | -| `$date-selected-range-hover-background` | Hover background for dates in selected range. | -| `$date-selected-range-focus-foreground` | Focus foreground for dates in selected range. | -| `$date-selected-range-focus-background` | Focus background for dates in selected range. | -| `$date-selected-current-range-foreground` | Foreground for current date in selected range. | -| `$date-selected-current-range-background` | Background for current date in selected range. | -| `$date-selected-current-range-hover-foreground` | Hover foreground for current date in selected range. | -| `$date-selected-current-range-hover-background` | Hover background for current date in selected range. | -| `$date-selected-current-range-focus-foreground` | Focus foreground for current date in selected range. | -| `$date-selected-current-range-focus-background` | Focus background for current date in selected range. | -| `$date-current-border-radius` | Border radius for current date. | -| `$date-current-border-color` | Border color for current date. | -| `$date-current-hover-border-color` | Hover border color for current date. | -| `$date-current-focus-border-color` | Focus border color for current date. | -| `$date-current-background` | Background for current date. | -| `$date-current-foreground` | Foreground for current date. | -| `$date-current-hover-background` | Hover background for current date. | -| `$date-current-focus-background` | Focus background for current date. | -| `$date-current-hover-foreground` | Hover foreground for current date. | -| `$date-current-focus-foreground` | Focus foreground for current date. | -| `$date-selected-current-border-color` | Border color for selected current date. | -| `$date-selected-current-hover-border-color` | Hover border color for selected current date. | -| `$date-selected-current-focus-border-color` | Focus border color for selected current date. | -| `$date-selected-current-background` | Background for selected current date. | -| `$date-selected-current-hover-background` | Hover background for selected current date. | -| `$date-selected-current-focus-background` | Focus background for selected current date. | -| `$date-selected-current-foreground` | Foreground for selected current date. | -| `$date-selected-current-hover-foreground` | Hover foreground for selected current date. | -| `$date-selected-current-focus-foreground` | Focus foreground for selected current date. | -| `$date-special-border-radius` | Border radius for special date. | -| `$date-special-border-color` | Border color for special date. | -| `$date-special-hover-border-color` | Hover border color for special date. | -| `$date-special-focus-border-color` | Focus border color for special date. | -| `$date-special-foreground` | Foreground for special date. Auto-derived from header-background. | -| `$date-special-background` | Background for special date. | -| `$date-special-hover-foreground` | Hover foreground for special date. | -| `$date-special-hover-background` | Hover background for special date. | -| `$date-special-focus-foreground` | Focus foreground for special date. | -| `$date-special-focus-background` | Focus background for special date. | -| `$date-special-range-border-color` | Border color for special date in range. | -| `$date-special-range-hover-border-color` | Hover border color for special date in range. | -| `$date-special-range-focus-border-color` | Focus border color for special date in range. | -| `$date-special-range-foreground` | Foreground for special date in range. | -| `$date-special-range-hover-foreground` | Hover foreground for special date in range. | -| `$date-special-range-focus-foreground` | Focus foreground for special date in range. | -| `$date-special-range-background` | Background for special date in range. | -| `$date-special-range-hover-background` | Hover background for special date in range. | -| `$date-special-range-focus-background` | Focus background for special date in range. | -| `$date-disabled-foreground` | Foreground for disabled dates. | -| `$date-disabled-range-foreground` | Foreground for disabled dates in selected range. | - -### Sass Theming - -Import the theming index, where the theme functions and component mixins live: +| **$header-background** | $header-foreground | Text color for the calendar header | +| | $picker-hover-foreground | Picker hover foreground | +| | $picker-focus-foreground | Picker focus foreground | +| | $date-current-background | Background for the current date | +| | $date-current-hover-foreground | Hover foreground for the current date | +| | $date-current-focus-foreground | Focus foreground for the current date | +| | $date-selected-current-foreground | Foreground for the currently selected date | +| | $date-selected-current-hover-foreground | Hover foreground for the currently selected date | +| | $date-selected-current-focus-foreground | Focus foreground for the currently selected date | +| | $date-special-border-color | Border color for special dates | +| | $date-special-hover-foreground | Hover foreground for special dates | +|**$content-background** | $content-foreground | Text and icon color inside calendar content area | +| | $weekend-color | Color for weekend dates | +| | $inactive-color | Color for dates outside active range | +| | $weekday-color | Color for weekday labels | +| | $picker-background | Picker background | +| | $date-hover-background | Background for hovered dates | +| | $date-hover-foreground | Foreground for hovered dates | +| | $date-focus-background | Background for focused dates | +| | $date-focus-foreground | Foreground for focused dates | +| | $date-selected-background | Background for selected dates | +| | $date-selected-hover-background | Hover background for selected dates | +| | $date-selected-focus-background | Focus background for selected dates | +| | $date-selected-foreground | Foreground for selected dates | +| | $date-selected-hover-foreground | Hover foreground for selected dates | +| | $date-selected-focus-foreground | Focus foreground for selected dates | +| | $date-selected-range-background | Background for selected date ranges | +| | $date-selected-range-foreground | Foreground for selected date ranges | +| | $date-disabled-foreground | Foreground for disabled dates | +| | $date-disabled-range-foreground | Foreground for disabled ranges | +| **$date-border-radius** | $date-range-border-radius | Controls the border radius for date ranges. | +| | $date-current-border-radius | Controls the border radius for the current date. | +| | $date-special-border-radius | Controls the border radius for special dates. | +| | $date-border-radius | If not specified and `$date-range-border-radius` is set, uses the value of `$date-range-border-radius`. | + +
+ {/* Bootstrap Theme Table */} +
+ + | Primary Property | Dependent Property | Description | +| --- | --- | --- | +| **$header-background** | $header-foreground | Text color for the calendar header | +| | $picker-background | Picker background | +| | $picker-hover-foreground | Picker hover foreground | +| | $weekday-color | Color for weekday labels | +| | $picker-focus-foreground | Picker focus foreground | +| | $date-special-border-color | Border color for special dates | +| | $date-special-focus-foreground | Focus foreground for special dates | +| **$content-background** | $content-foreground | Text and icon color inside calendar content area | +| | $weekend-color | Color for weekend dates | +| | $inactive-color | Color for dates outside active range | +| | $weekday-color | Color for weekday labels | +| | $date-hover-background | Background for hovered dates | +| | $date-hover-foreground | Foreground for hovered dates | +| | $date-focus-background | Background for focused dates | +| | $date-focus-foreground | Foreground for focused dates | +| | $date-current-background | Background for the current date | +| | $date-current-foreground | Foreground for the current date | +| | $date-current-border-color | Border color for the current date | +| | $date-selected-background | Background for selected dates | +| | $date-selected-current-background | Background for the currently selected date | +| | $date-selected-foreground | Foreground for selected dates | +| | $date-selected-current-foreground | Foreground for the currently selected date | +| | $date-selected-special-border-color | Border color for selected special dates | +| | $date-selected-special-hover-border-color | Hover border color for selected special dates | +| | $date-selected-special-focus-border-color | Focus border color for selected special dates | +| | $date-selected-range-background | Background for selected date ranges | +| | $date-selected-range-foreground | Foreground for selected date ranges | +| | $date-disabled-foreground | Foreground for disabled dates | +| | $date-disabled-range-foreground | Foreground for disabled ranges | +| **$date-border-radius** | $date-range-border-radius | Controls the border radius for date ranges. | +| | $date-current-border-radius | Controls the border radius for the current date. | +| | $date-special-border-radius | Controls the border radius for special dates. | +| | $date-border-radius | If not specified and `$date-range-border-radius` is set, uses the value of `$date-range-border-radius`. | + +
+ {/* Indigo Theme Table */} +
+ + | Primary Property | Dependent Property | Description | +| --- | --- | --- | +| **$header-background** | $header-foreground | Text color for the calendar header | +| | $picker-background | Picker background | +| | $picker-hover-foreground | Picker hover foreground | +| | $picker-focus-foreground | Picker focus foreground | +| | $navigation-hover-color | Navigation hover color | +| | $navigation-focus-color | Navigation focus color | +| | $date-current-background | Background for the current date | +| | $date-current-border-color | Border color for the current date | +| | $date-current-hover-background | Background for hovered current date | +| | $date-current-hover-border-color | Border color for hovered current date | +| | $date-current-focus-background | Background for focused current date | +| | $date-current-focus-border-color | Border color for focused current date | +| | $date-current-foreground | Foreground for the current date | +| | $date-current-hover-foreground | Foreground for hovered current date | +| | $date-current-focus-foreground | Foreground for focused current date | +| | $date-selected-current-border-color | Border color for the currently selected date | +| **$content-background** | $content-foreground | Text and icon color inside calendar content area | +| | $weekend-color | Color for weekend dates | +| | $inactive-color | Color for dates outside active range | +| | $weekday-color | Color for weekday labels | +| | $date-hover-background | Background for hovered dates | +| | $date-hover-foreground | Foreground for hovered dates | +| | $date-focus-background | Background for focused dates | +| | $date-focus-foreground | Foreground for focused dates | +| | $date-selected-background | Background for selected dates | +| | $date-selected-current-background | Background for the currently selected date | +| | $date-selected-foreground | Foreground for selected dates | +| | $date-selected-current-foreground | Foreground for the currently selected date | +| | $date-selected-current-border-color | Border color for the currently selected date | +| | $date-selected-range-background | Background for selected date ranges | +| | $date-selected-range-foreground | Foreground for selected date ranges | +| | $date-selected-current-range-background | Background for the current date in a selected range | +| | $date-selected-current-range-hover-background | Hover background for the current date in a selected range | +| | $date-selected-current-range-foreground | Foreground for the current date in a selected range | +| | $date-disabled-foreground | Foreground for disabled dates | +| | $date-disabled-range-foreground | Foreground for disabled ranges | +| **$date-border-radius** | $date-range-border-radius | Controls the border radius for date ranges. | +| | $date-current-border-radius | Controls the border radius for the current date. | +| | $date-special-border-radius | Controls the border radius for special dates. | +| | $date-border-radius | If not specified and `$date-range-border-radius` is set, uses the value of `$date-range-border-radius`. | + +
+ +
+
{/* .theme-switcher-wrapper */} + +To get started with styling the calendar, we need to import the `index` file, where all the theme functions and component mixins live: ```scss @use "igniteui-angular/theming" as *; + +// IMPORTANT: Prior to Ignite UI for Angular version 13 use: +// @import '~igniteui-angular/lib/core/styles/themes/index'; ``` -Create a theme that extends . Specifying just `$header-background` and `$content-background` computes the related state colors and contrast foregrounds automatically, and you can still override any parameter: +Following the simplest approach, we create a new theme that extends the and by specifying just the `$header-background` and `$content-background` parameters, the theme will automatically compute appropriate state colors and contrast foregrounds. Of course, you're still free to override any of the theme parameters with custom values if needed. ```scss $custom-calendar-theme: calendar-theme( @@ -517,7 +658,7 @@ $custom-calendar-theme: calendar-theme( ); ``` -Pass the custom theme: +The last step is to pass the custom calendar theme: ```scss :host { @@ -525,11 +666,13 @@ Pass the custom theme: } ``` -### Tailwind + + +### Styling with Tailwind -Style the calendar with the custom Tailwind utility classes. First, [set up Tailwind](/themes/misc/tailwind-classes). +You can style the `calendar` using our custom Tailwind utility classes. Make sure to [set up Tailwind](/themes/misc/tailwind-classes) first. -Along with the Tailwind import in your global stylesheet, add the theme utilities: +Along with the tailwind import in your global stylesheet, you can apply the desired theme utilities as follows: ```scss @import "tailwindcss"; @@ -537,9 +680,15 @@ Along with the Tailwind import in your global stylesheet, add the theme utilitie @use 'igniteui-theming/tailwind/utilities/material.css'; ``` -The utility file includes both `light` and `dark` variants. Use `light-*` classes for the light theme and `dark-*` classes for the dark theme, appending the component name after the prefix — `light-calendar`, `dark-calendar`. These classes enable dynamic theme calculations, and you override the generated CSS variables using arbitrary properties. After the colon, provide any valid CSS color format (HEX, CSS variable, RGB, etc.). +The utility file includes both `light` and `dark` theme variants. + +- Use `light-*` classes for the light theme. +- Use `dark-*` classes for the dark theme. +- Append the component name after the prefix, e.g., `light-calendar`, `dark-calendar`. + +Once applied, these classes enable dynamic theme calculations. From there, you can override the generated CSS variables using `arbitrary properties`. After the colon, provide any valid CSS color format (HEX, CSS variable, RGB, etc.). -Find the full list of properties in the : +You can find the full list of properties in the . The syntax is as follows: ```html -The exclamation mark (`!`) is required so the utility class takes precedence. Tailwind applies styles in layers, and without marking these styles as important they get overridden by the component's default theme. +The exclamation mark(`!`) is required to ensure the utility class takes precedence. Tailwind applies styles in layers, and without marking these styles as important, they will get overridden by the component’s default theme. - +At the end your calendar should look like this: -## Accessibility - -### Keyboard Interaction - -When the calendar is focused, use: - -| Key | Action | -| --- | --- | -| PageUp | Move to the previous month | -| PageDown | Move to the next month | -| Shift + PageUp | Move to the previous year | -| Shift + PageDown | Move to the next year | -| Home | Focus the first day of the month, or the first month/year in view | -| End | Focus the last day of the month, or the last month/year in view | -| Arrow keys | Navigate through days, months, or years in the active view (disabled dates are skipped) | -| Enter / Space | Select the focused day, or open/confirm the focused month or year | - -When the previous or next month button in the subheader is focused, press Space or Enter to scroll the next or previous month into view. When the month button is focused, Space or Enter opens the months view; when the year button is focused, it opens the decade view. - -Day navigation is continuous — arrow keys move through days across month boundaries and change the month in view as needed. - - -Tab navigation reaches these stops: the previous-month button, the month button, the year button, the next-month button, and one date in the grid (the selected date, the current date, or the first focusable date). In multi and range selection, only the first selected date is part of the tab sequence; move between dates in the grid with the arrow keys. - - -### Screen Readers / ARIA - -The calendar view exposes `role="grid"` and tracks the focused cell with `aria-activedescendant`, and sets `aria-multiselectable` when `selection` is `multi` or `range`. The navigation buttons and the month/year pickers expose `role="button"` with localized `aria-label`s, and off-screen live regions announce the presented month and year. All labels come from the calendar resource strings, so they follow the component's `locale` and can be overridden through `resourceStrings`. - -### Accessibility Compliance - -Infragistics evaluates Ignite UI for Angular components against Section 508 and WCAG guidelines — see the [Accessibility Compliance](/interactivity/accessibility-compliance) topic for the full component-by-component matrix. - -| Criterion | How the Calendar complies | -| --- | --- | -| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html) / [2.1.2 No Keyboard Trap](https://www.w3.org/WAI/WCAG21/Understanding/no-keyboard-trap.html) | Every view (days, months, years) is fully operable from the keyboard — paging, navigation, and selection all have a documented key binding, and arrow-key navigation moves continuously between days without trapping focus. | -| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) | The view area exposes `role="grid"` with `aria-activedescendant` for the focused cell and `aria-multiselectable` in `multi`/`range` selection; the navigation and picker buttons expose `role="button"` with localized `aria-label`s. | -| [4.1.3 Status Messages](https://www.w3.org/WAI/WCAG21/Understanding/status-messages.html) | Off-screen live regions announce the presented month and year as the user navigates, so the change is available to assistive technology without moving focus. | - -**Your responsibilities** - -- Keep sufficient color contrast between the calendar's background and its date/text colors when customizing the theme — see [Styling](#styling). -- Preserve a logical tab order when embedding the calendar in a custom layout, so the documented Tab stops (navigation buttons, then the grid) stay reachable in sequence. -- If you override `resourceStrings`, keep the replacement labels as descriptive as the defaults they replace. - -## Troubleshooting - -**How do I register the calendar with an `NgModule` instead of the standalone directives?** - -Before standalone components, the calendar was imported through `IgxCalendarModule`. Add it — together with `BrowserAnimationsModule` — to your `AppModule`: - -```typescript -// app.module.ts -import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; -import { IgxCalendarModule } from 'igniteui-angular/calendar'; -// import { IgxCalendarModule } from '@infragistics/igniteui-angular'; for licensed package - -@NgModule({ - imports: [..., BrowserAnimationsModule, IgxCalendarModule], -}) -export class AppModule {} -``` - -Standalone imports (`IGX_CALENDAR_DIRECTIVES` or `IgxCalendarComponent`) are available as of `16.0.0` and are the recommended approach. - -**My Sass `@import` of the theming index no longer resolves.** - -Prior to Ignite UI for Angular version 13, import the themes from the legacy path instead of `@use "igniteui-angular/theming"`: - -```scss -@import '~igniteui-angular/lib/core/styles/themes/index'; -``` - -**Arrow keys don't move focus between days when I press Tab.** - -From version 10.2.0, Tab no longer steps through the days view; use the arrow keys to move between dates. From version 8.2.0, arrow-key navigation does not focus days outside the current month — it changes the month in view instead. + ## API References - +
- - - - - - ## Additional Resources +
+ Our community is active and always welcoming to new ideas. - [Ignite UI for Angular **Forums**](https://www.infragistics.com/community/forums/f/ignite-ui-for-angular)