@ng-solid/design-system 22.1.1 → 22.2.0

package/README.md

@@ -1,76 +1,134 @@
-# Angular UI Components
+# @ng-solid/design-system
 
-[![NPM version][npm-image]][npm-url]
-
-[npm-image]: https://img.shields.io/npm/v/@ng-solid/facebook.svg?style=flat-square
-[npm-url]: https://www.npmjs.com/@ng-solid/facebook
-
-An Angular UI component library based on Ant Design.
+Arvisfy is the default ng-solid design-system preset. It combines Angular
+standalone components, Tailwind CSS composition from SCSS, BEM `ns-*` class
+contracts and a strict three-tier token architecture.
 
 ## Installation
 
 ```bash
-$ ng new PROJECT_NAME
-$ cd PROJECT_NAME
-$ ng add @ng-solid/design-system
+pnpm add @ng-solid/design-system @ng-solid/icons
+pnpm add -D tailwindcss @tailwindcss/postcss
+```
+
+Tailwind is optional unless the application consumes the semantic utility
+bridge. Configure `@tailwindcss/postcss` in the application's PostCSS setup.
+
+Import the Tailwind semantic bridge once in the application stylesheet:
+
+```css
+@import '@ng-solid/design-system/themes/tailwind.css';
 ```
 
-You can also install `@ng-solid/design-system` with npm or yarn
+Register Arvisfy in the Angular application configuration:
 
-## Usage
+```ts
+import { Arvisfy, provideNsTheme } from '@ng-solid/design-system';
 
-Import the component module you want to use in your `app.module.ts` file
-or [feature modules](https://angular.io/guide/feature-modules) as you need.
+export const appConfig = {
+  providers: [provideNsTheme({ preset: Arvisfy, colorScheme: 'system' })]
+};
+```
 
-### Buttons
+`system` follows `prefers-color-scheme`. Explicit `light` and `dark` choices
+are persisted by `NsThemeService` and applied without reloading:
 
 ```ts
-import { NsButtonModule } from '@ng-solid/design-system';
+import { inject } from '@angular/core';
+import { NsThemeService } from '@ng-solid/design-system';
 
-@NgModule({
-  imports: [...NsButtonModule]
-})
-export class AppModule {}
+const theme = inject(NsThemeService);
+theme.setScheme('dark');
 ```
 
-and in your html template
+## Extend the preset
+
+Use `defineNsPreset` so custom presets retain the primitive → semantic →
+component dependency contract:
 
-```angular2html
-<ns-button label="My Button" [theme]="true"></ns-button>
+```ts
+import { defineNsPreset, Arvisfy } from '@ng-solid/design-system';
+
+export const ProductTheme = defineNsPreset(Arvisfy, {
+  name: 'product',
+  primitive: {
+    color: {
+      brand: { 500: '#0052ff' }
+    }
+  },
+  semantic: {
+    colorScheme: {
+      light: { color: { primary: '{primitive.color.brand.500}' } },
+      dark: { color: { primary: '{primitive.color.brand.500}' } }
+    }
+  },
+  components: {
+    button: { borderColor: '{semantic.color.primary}' }
+  }
+});
 ```
 
-### Input groups
+See the packaged `themes/README.md` for the Arvisfy design principles and token
+rules.
+
+## Components
 
-`ns-input-group` is a visual wrapper. Keep `formControlName`, `formControl` or
-`ngModel` on every input, checkbox or radio inside the group.
+Components are imported directly from the package:
 
 ```ts
 import {
+  NsButtonComponent,
+  NsDatePickerComponent,
   NsInputComponent,
   NsInputGroupAddonComponent,
-  NsInputGroupComponent
+  NsInputGroupComponent,
+  NsModalComponent
 } from '@ng-solid/design-system';
 ```
 
 ```html
-<ns-input-group
-  append=".tienda-aprovecha.do"
-  label="Store URL"
-  size="md"
-  [wrap]="false"
->
-  <ns-input formControlName="domain" placeholder="demo" />
-</ns-input-group>
+<ns-button variant="primary">Guardar cambios</ns-button>
 
-<ns-input-group label="Amount">
+<ns-input-group>
   <ns-input-group-addon>$</ns-input-group-addon>
   <ns-input formControlName="amount" ariaLabel="Amount" />
   <ns-input-group-addon>USD</ns-input-group-addon>
-  <ns-button label="Apply" />
 </ns-input-group>
 ```
 
-The group supports text addons through `prepend` and `append`, repeated
-`ns-input-group-addon` elements, buttons on either side, multiple inputs,
-checkbox/radio content, `sm | md | lg` sizing and configurable wrapping. Labels
-belong outside the visual row and are associated with the first `ns-input`.
+`ns-input-group` is only a layout wrapper. It has no `label` or `wrap` inputs;
+put labels and form directives on the projected `ns-input` control.
+
+Application templates should style their own layout with BEM `ns-*` classes.
+Library component templates never expose Tailwind utilities directly.
+
+`ns-button` uses projected content and the semantic `primary`, `secondary`,
+`tertiary`, `success`, and `danger` variants; `color`, `label`, and the former
+`theme` input are not part of its API. `NsModalComponent` supports projected modal content or a
+typed `contentComponent` supplied through `NsModalService`; `nsTemplate` no
+longer registers templates with a modal reference.
+
+The package's primary component API is:
+
+- `NsAccordionComponent`, `NsAlertComponent`, `NsAvatarComponent`,
+  `NsBadgeComponent`, `NsBreadcrumbsComponent`, `NsButtonComponent`,
+  `NsButtonGroupComponent`, `NsCardComponent`, `NsCheckboxComponent`,
+  `NsChipComponent`, `NsSelectorListComponent`.
+- `NsDatePickerComponent`, `NsDateRangePickerComponent`,
+  `NsDescriptionComponent`, `NsDrawerComponent`, `NsInputComponent`,
+  `NsInputGroupComponent`, `NsInputCodeComponent`, `NsLinkComponent`,
+  `NsListBoxComponent`, `NsMeterComponent`, `NsModalComponent`,
+  `NsInputNumberComponent`, `NsPaginationComponent`, `NsPopoverComponent`,
+  `NsProgressBarComponent`.
+- `NsRadioComponent`, `NsRadioGroupComponent`, `NsInputSearchComponent`,
+  `NsDividerComponent`, `NsSkeletonComponent`, `NsSliderComponent`,
+  `NsSurfaceComponent`, `NsSwitchComponent`, `NsTabsComponent`,
+  `NsTagGroupComponent`, `NsTextAreaComponent`, `NsToastComponent`, and
+  `NsTooltipComponent`.
+
+Composition helpers such as `NsAccordionItemComponent`,
+`NsBreadcrumbItemComponent`, `NsCardHeaderComponent`, `NsCardBodyComponent`,
+`NsCardFooterComponent`, `NsListBoxOptionComponent`,
+`NsSelectorListItemComponent`, `NsTabComponent`, `NsTagComponent`, and
+`NsTooltipDirective` are exported from the same entry point. The legacy
+Dropdown API and its legacy toast contracts are not exported.