feat: add presentational country flag component and docs (#DS-1405) by NikGurev · Pull Request #1711 · koobiq/angular-components

NikGurev · 2026-07-07T15:44:46Z

Adds KbqFlag (<kbq-flag>) — a small, presentational country-flag component. The component owns only
presentation and accessibility; the flag graphic itself is supplied by the consumer as projected content.

Content projection, not data. The flag SVG is projected ([innerHTML] or a child element); the
library ships no flag data and has no dependency on any flag package.
Inputs: shape (rectangle / square / circle), shadow (inset / none, a theme-adaptive
inset hairline), empty (neutral
placeholder), plus the a11y contract — label → role="img" + accessible name, decorative →
aria-hidden.
Sizing follows font-size (height: 1em) with an aspect-ratio box; no hardcoded size presets.
Zero coupling / trivial customization. Any custom or non-country flag is just different projected
SVG (or any element) — no API, no registration. The library stays data-free and dependency-free.
Simple and conventional. Rendering an inline <svg> is the most common way to show vector icons on
the web — no image requests, no data-URL/base64 wrapping, no runtime fetch or icon-registry
indirection. Consumers just import a flag string and drop it in.

github-actions · 2026-07-07T15:49:16Z

Visit the preview URL for this PR (updated for commit af3d09a):

https://koobiq-next--prs-1711-6vzyyk8c.web.app

_{(expires Mon, 13 Jul 2026 11:30:07 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: c9e37e518febda70d0317d07e8ceb35ac43c534c}

github-actions · 2026-07-07T15:49:18Z

🚨 E2E tests failed

Review the report for details.

💡 Comment /approve-snapshots to approve snapshot changes.

github-actions · 2026-07-08T15:41:19Z

🚨 E2E tests failed

Review the report for details.

💡 Comment /approve-snapshots to approve snapshot changes.

github-actions · 2026-07-08T16:19:09Z

🚨 E2E tests failed

Review the report for details.

💡 Comment /approve-snapshots to approve snapshot changes.

NikGurev · 2026-07-08T16:21:13Z

/approve-snapshots

github-actions · 2026-07-08T16:21:25Z

🔄 Updating snapshots.

github-actions · 2026-07-08T16:26:36Z

✅ Snapshots updated!

NikGurev · 2026-07-08T16:31:52Z

/approve-snapshots

github-actions · 2026-07-08T16:32:05Z

🔄 Updating snapshots.

github-actions · 2026-07-08T16:36:18Z

✅ Snapshots updated!

NikGurev · 2026-07-08T16:41:04Z

Sample flag svg, so not quite filled into shaped

artembelik · 2026-07-09T07:30:02Z

примеры не работают

artembelik · 2026-07-09T07:30:57Z

мб добавим callout по аналогии с другими компонентами?

Copilot

Pull request overview

Adds a new @koobiq/components/flag package that provides <kbq-flag> — a small presentational wrapper for consumer-supplied flag graphics — and wires it into docs, examples, E2E, and the components-dev playground.

Changes:

Introduces KbqFlag component (+ types, styles, NgModule export, unit tests, API extractor/guard output).
Adds docs content + multiple docs examples (including a virtual-scroll select example) and a components-dev demo app.
Adds E2E route + Playwright visual-regression coverage and updates workspace config to include the new package.

Reviewed changes

Copilot reviewed 32 out of 36 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
yarn.lock	Locks the newly added `country-flag-icons` dependency.
tsconfig.json	Adds a path alias for `@koobiq/components/flag`.
tools/public_api_guard/components/flag.api.md	New API guard snapshot for the Flag package.
tools/api-extractor/config.json	Registers `flag` for API extraction.
packages/e2e/routes.ts	Registers the Flag E2E component route.
packages/docs-examples/example-module.ts	Registers Flag examples (and some additional non-Flag examples) for docs.
packages/docs-examples/components/flag/ng-package.json	Adds ng-packagr config for the Flag docs-examples subpackage.
packages/docs-examples/components/flag/index.ts	Declares/exports the Flag docs examples module and examples.
packages/docs-examples/components/flag/flag-stylized/flag-stylized-example.ts	Adds a stylized flag docs example.
packages/docs-examples/components/flag/flag-square/flag-square-example.ts	Adds a square-flag docs example.
packages/docs-examples/components/flag/flag-sizes/flag-sizes-example.ts	Adds a flag sizing guidance docs example.
packages/docs-examples/components/flag/flag-overview/flag-overview-example.ts	Adds an overview grid docs example.
packages/docs-examples/components/flag/flag-language/flag-language-example.ts	Adds an a11y guidance example (“flag is not a language”).
packages/docs-examples/components/flag/flag-fallback/flag-fallback-example.ts	Adds a fallback/placeholder example using `hasFlag`.
packages/docs-examples/components/flag/flag-circle/flag-circle-example.ts	Adds a circular-flag docs example.
packages/docs-examples/components/flag/flag-aspect-ratio/flag-aspect-ratio-example.ts	Adds a select + virtual scroll example demonstrating sizing/aspect ratio.
packages/components/flag/public-api.ts	Exposes Flag public API surface.
packages/components/flag/ng-package.json	Adds ng-packagr config for the new component package.
packages/components/flag/module.ts	Provides `KbqFlagModule` for NgModule consumers.
packages/components/flag/index.ts	Adds package entrypoint export.
packages/components/flag/flag.types.ts	Defines `KbqFlagShape`/`KbqFlagShadow` types.
packages/components/flag/flag.ts	Implements the `KbqFlag` component host bindings and inputs.
packages/components/flag/flag.spec.ts	Adds unit tests for projection, modifiers, and a11y host attributes.
packages/components/flag/flag.scss	Adds styling for sizing, shape, inset shadow, stylized mode, and empty placeholder.
packages/components/flag/flag.ru.md	Adds Russian docs for usage/a11y guidelines + examples.
packages/components/flag/flag.en.md	Adds English docs for usage/a11y guidelines + examples.
packages/components/flag/e2e.ts	Adds E2E demo component for visual coverage without external flag data.
packages/components/flag/e2e.playwright-spec.ts	Adds Playwright screenshot coverage (light/dark).
packages/components-dev/flag/tsconfig.app.json	Adds TS config for the flag dev app.
packages/components-dev/flag/module.ts	Adds dev app module wiring for Flag docs examples.
packages/components-dev/flag/main.ts	Bootstraps the Flag dev app.
package.json	Adds `country-flag-icons` dev dependency and `dev:flag` script.
apps/docs/src/app/structure.ts	Registers Flag in docs navigation structure.
angular.json	Adds a `dev-flag` Angular project configuration.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

artembelik · 2026-07-09T07:35:26Z

+                        ru: 'Flag',
+                        en: 'Flag'
+                    },
+                    svgPreview: '',


@rmnturov нужна иконка

NikGurev · 2026-07-09T07:56:57Z

примеры не работают

#1715 поправили тут

rmnturov · 2026-07-09T15:51:01Z

скроллбар не стилизовался

rmnturov · 2026-07-10T02:38:41Z

Отступ еще как-то ненужный у скроллбара

У самого окна не нужно паддингов. Паддинги нужны уже внутри самое прокручиваемой области (список опций)

rmnturov · 2026-07-10T03:20:14Z

По stylized (и его реализации в flag.scss) — это был просто пример для документации, демонстрирующий возможную кастомную стилизацию (градиент, тень, скругление), а не универсальное решение, которое стоит зашивать в сам компонент. Конкретные значения градиента/тени/radius лучше не хардкодить в библиотечном коде — предлагаю либо вынести это в пример кастомизации в доках (без встроенного пропа), либо вынести значения в переопределяемые CSS-переменные, если проп всё же остаётся.

rmnturov · 2026-07-10T07:06:45Z

В мире не менее (а то и более) распространены флаги с пропорцией 4:3 — не только из country-flag-icons. Хотелось бы, чтобы обёртка могла работать и с такими флагами, а не только с жёстко зафиксированными 3:2.

NikGurev · 2026-07-10T07:43:50Z

скроллбар не стилизовался

@rmnturov это select с виртуальным скроллом, известная проблема. Использовал его, так как из-за большого количества svg страница подтормаживала

lskramarov · 2026-07-10T07:48:37Z

скроллбар не стилизовался

@rmnturov это select с виртуальным скроллом, известная проблема. Использовал его, так как из-за большого количества svg страница подтормаживала

@NikGurev количество стран конечное и сравнительно не большое, что бы использовать вирт скрол, давай без него

NikGurev · 2026-07-10T08:55:16Z

В мире не менее (а то и более) распространены флаги с пропорцией 4:3 — не только из country-flag-icons. Хотелось бы, чтобы обёртка могла работать и с такими флагами, а не только с жёстко зафиксированными 3:2.

добавил кастомизацию через --kbq-flag-aspect-ratio

NikGurev · 2026-07-10T08:55:49Z

По stylized (и его реализации в flag.scss) — это был просто пример для документации, демонстрирующий возможную кастомную стилизацию (градиент, тень, скругление), а не универсальное решение, которое стоит зашивать в сам компонент. Конкретные значения градиента/тени/radius лучше не хардкодить в библиотечном коде — предлагаю либо вынести это в пример кастомизации в доках (без встроенного пропа), либо вынести значения в переопределяемые CSS-переменные, если проп всё же остаётся.

вынес кастомизацию в пример, border-radius кастомизируется через --kbq-flag-border-radius

github-actions · 2026-07-10T08:59:54Z

🚨 E2E tests failed

Review the report for details.

💡 Comment /approve-snapshots to approve snapshot changes.

NikGurev · 2026-07-10T09:43:17Z

/approve-snapshots

github-actions · 2026-07-10T09:43:31Z

🔄 Updating snapshots.

github-actions · 2026-07-10T09:48:16Z

✅ Snapshots updated!

github-actions · 2026-07-10T10:03:32Z

🚨 E2E tests failed

Review the report for details.

💡 Comment /approve-snapshots to approve snapshot changes.

NikGurev · 2026-07-10T10:41:29Z

/approve-snapshots

github-actions · 2026-07-10T10:41:42Z

🔄 Updating snapshots.

- drop `size` tokens, add `stylized` and `isEmpty` inputs

…-1405)

github-actions · 2026-07-10T10:48:13Z

🚨 E2E tests failed

Review the report for details.

💡 Comment /approve-snapshots to approve snapshot changes.

github-actions · 2026-07-10T11:30:13Z

🚨 E2E tests failed

Review the report for details.

💡 Comment /approve-snapshots to approve snapshot changes.

NikGurev self-assigned this Jul 8, 2026

NikGurev added enhancement New feature or request 20.x labels Jul 8, 2026

NikGurev marked this pull request as ready for review July 8, 2026 16:17

NikGurev requested a review from lskramarov as a code owner July 8, 2026 16:17

NikGurev commented Jul 8, 2026

View reviewed changes

artembelik requested a review from Copilot July 9, 2026 07:27

Copilot started reviewing on behalf of artembelik July 9, 2026 07:28 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread package.json

Comment thread packages/docs-examples/example-module.ts

Comment thread apps/docs/src/app/structure.ts

Comment thread packages/components/flag/flag.en.md Outdated

artembelik reviewed Jul 9, 2026

View reviewed changes

Comment thread packages/components/flag/flag.ts Outdated

artembelik reviewed Jul 9, 2026

View reviewed changes

Comment thread package.json

NikGurev requested a review from rmnturov July 9, 2026 09:27

lskramarov approved these changes Jul 10, 2026

View reviewed changes

NikGurev and others added 11 commits July 10, 2026 13:42

feat: add presentational country flag component and docs (#DS-1405)

e2e489d

refactor(flag): simplify API and rework examples (#DS-1405)

1c3fbdd

- drop `size` tokens, add `stylized` and `isEmpty` inputs

refactor(flag): use inline svg in examples and simplify overview (#DS…

b0a4559

…-1405)

chore: review docs, use direct icons instead pipe

6f72899

test: updated e2e snapshots

1f04f95

chore: update e2e

2bf7c81

test: updated e2e snapshots

c7608a8

chore: after review

b631004

refactor(flag): drop hardcoded stylized, make aspect

939465d

refactor(flag): returned back text

6c714e4

test: updated e2e snapshots

119039e

NikGurev force-pushed the feat/DS-1405 branch from d2907ea to 119039e Compare July 10, 2026 10:43

docs(flag): improve russian article wording (#DS-1405)

af3d09a

Uh oh!

Conversation

NikGurev commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 7, 2026

🚨 E2E tests failed

Uh oh!

github-actions Bot commented Jul 8, 2026

🚨 E2E tests failed

Uh oh!

github-actions Bot commented Jul 8, 2026

🚨 E2E tests failed

Uh oh!

NikGurev commented Jul 8, 2026

Uh oh!

github-actions Bot commented Jul 8, 2026

Uh oh!

github-actions Bot commented Jul 8, 2026

Uh oh!

NikGurev commented Jul 8, 2026

Uh oh!

github-actions Bot commented Jul 8, 2026

Uh oh!

github-actions Bot commented Jul 8, 2026

Uh oh!

NikGurev Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

artembelik commented Jul 9, 2026

Uh oh!

artembelik commented Jul 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

artembelik Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

NikGurev commented Jul 9, 2026

Uh oh!

Uh oh!

rmnturov commented Jul 9, 2026

Uh oh!

rmnturov commented Jul 10, 2026

Uh oh!

rmnturov commented Jul 10, 2026

Uh oh!

rmnturov commented Jul 10, 2026

Uh oh!

NikGurev commented Jul 10, 2026

Uh oh!

lskramarov commented Jul 10, 2026

Uh oh!

NikGurev commented Jul 10, 2026

Uh oh!

NikGurev commented Jul 10, 2026

Uh oh!

github-actions Bot commented Jul 10, 2026

🚨 E2E tests failed

Uh oh!

NikGurev commented Jul 10, 2026

Uh oh!

github-actions Bot commented Jul 10, 2026

Uh oh!

github-actions Bot commented Jul 10, 2026

Uh oh!

github-actions Bot commented Jul 10, 2026

🚨 E2E tests failed

Uh oh!

NikGurev commented Jul 7, 2026 •

edited

Loading

github-actions Bot commented Jul 7, 2026 •

edited

Loading