@fasteros/themes 1.0.0

package/README.md

@@ -0,0 +1,310 @@
+# [FasterOS](https://fasteros.com/api)
+[![price](https://img.shields.io/badge/price-COMMERCIAL-blue)](https://fasteros.com/license)
+
+FasterOS is a set of tools to accelerate software development.
+
+# [Faster Themes](https://fasteros.com/api)
+[![Passing](https://img.shields.io/badge/Passing-Angular_19-green)](https://fasteros.com/license) [![Passing](https://img.shields.io/badge/Passing-Node_>=18.19.1-green)](https://fasteros.com/license)
+
+A faster, better way to style code.
+
+Faster Themes moves styling from static CSS into typed theme objects so it can be generated, swapped, and edited at runtime. No build step for restyles. No CSS hunt for a misbehaving class.
+
+- **Free** — use any of the built-in generated themes, or generate your own at runtime from 13 palette presets × 5 style profiles × 5 purpose profiles.
+- **Paid** — `$1/mo. per Theme Editor + $0.00003 per read/write` to author and host custom themes via [FasterOS](https://fasteros.com/api). A site with 100k monthly visits runs ~$4/mo. Hosting included.
+
+## [Demo Site](https://fasteros.com/api)
+
+
+## Install
+
+```bash
+npm i @fasteros/themes @angular/animations
+```
+
+Add `FasterThemesModule` to your `AppModule`:
+
+```ts
+import { FasterThemesModule } from '@fasteros/themes';
+
+@NgModule({
+  imports: [BrowserModule, FasterThemesModule],
+  declarations: [AppComponent],
+  bootstrap: [AppComponent],
+})
+export class AppModule {}
+```
+
+That gives you the `n*` directives, the `<accordion>` component, the `<faster-theme-generator>` component, and the `FasterThemesService`.
+
+---
+
+## Two ways to get a theme
+
+### Option A — Generate one locally (free)
+
+`<faster-theme-generator>` builds a full `FasterTheme` from four inputs and emits it via `(themeGenerated)`. No backend, no API key.
+
+```ts
+import { Component } from '@angular/core';
+import { FasterTheme } from '@fasteros/themes';
+
+@Component({
+  selector: 'app-root',
+  template: `
+    <faster-theme-generator
+      themeStyle="modern"
+      purpose="dashboard"
+      palette="corporate"
+      layout="row wrap"
+      (themeGenerated)="theme = $event">
+    </faster-theme-generator>
+
+    <div nContainer="Wide" [theme]="theme">
+      <div nType="H1" [theme]="theme">Hello</div>
+      <div nButton="Default Style" [theme]="theme">Click me</div>
+    </div>
+  `,
+})
+export class AppComponent {
+  theme?: FasterTheme;
+}
+```
+
+You can also generate from TypeScript without putting the component in your template:
+
+```ts
+import { ThemeGeneratorComponent } from '@fasteros/themes';
+
+const gen = new ThemeGeneratorComponent();
+gen.themeStyle = 'bold';
+gen.purpose = 'form';
+gen.palette = 'finance';
+const theme = gen.generate();
+```
+
+#### Generator inputs
+
+| Input | Values | Effect |
+|---|---|---|
+| `themeStyle` | `modern`, `classic`, `minimal`, `bold`, `playful` | Font family, weights, border radius, shadows |
+| `purpose` | `marketing`, `dashboard`, `documentation`, `form`, `gallery` | Padding density, button sizing, heading emphasis, accordion mode |
+| `palette` | a preset name (see below) or a custom `Palette[]` | Color story (8 semantic roles) |
+| `layout` | `row`, `row wrap` (default), `column`, etc. | Default `flex-flow` for containers and accordions |
+| `elevation` | `none`, `small`, `medium` (default), `large` | Container/button box-shadow depth |
+| `textShadow` | `none` (default), `small`, `medium`, `large` | Typography shadow depth |
+| `name` | optional `string` | Override theme name (default: `"<Style> <Palette> <Purpose>"`) |
+| `responsive*` | optional numbers | Override the seven responsive sizing knobs |
+
+#### Palette presets
+
+Each preset defines 8 semantic roles: `Primary`, `Secondary`, `Accent`, `Highlight`, `Surface`, `Muted`, `Subtle`, `Inverse`.
+
+| Group | Presets |
+|---|---|
+| Aesthetic | `ocean`, `forest`, `sunset`, `monochrome`, `pastel` |
+| Business | `corporate`, `healthcare`, `finance`, `tech`, `legal`, `hospitality`, `retail`, `education` |
+
+---
+
+### Option B — Load themes from FasterOS
+
+Once you have:
+
+- ✅ Created a Team on [FasterOS](https://fasteros.com/api)
+- ✅ Generated an API key
+- ✅ Created or selected a Theme
+
+call `initThemes()` at startup:
+
+```ts
+import { Component } from '@angular/core';
+import { FasterThemesService } from '@fasteros/themes';
+
+@Component({
+  selector: 'app-root',
+  templateUrl: './app.component.html',
+})
+export class AppComponent {
+  constructor(public fasterThemes: FasterThemesService) {
+    this.fasterThemes.initThemes('YOUR_API_KEY');
+  }
+}
+```
+
+The service fetches `{ companyId, themes: FasterTheme[] }` once at init and populates `fasterThemes.allThemes`. Pass an optional `themeId` as the second argument to load a single theme. On failure (missing key, network error, non-2xx) the call logs and returns silently — `getTheme()` falls back to the built-in `defaultStyle`.
+
+Then refer to themes by name in your template:
+
+```html
+<div *ngIf="fasterThemes.allThemes?.length">
+  <div nContainer="Full Width" theme="base">
+    <div nType="H1" theme="base">Headline</div>
+    <div nButton="Create" theme="base">Add</div>
+  </div>
+</div>
+```
+
+---
+
+## Using a theme
+
+### `n*` directives
+
+Apply theme-driven styles to any element. They re-apply automatically when the bound theme reference changes.
+
+```html
+<div nContainer="Wide" [theme]="theme">
+  <div nType="H1" [theme]="theme">Hello</div>
+  <div nButton="Default Style" [theme]="theme">Click me</div>
+  <div nColor="Primary" [theme]="theme">Tinted block</div>
+  <div nClass="justifyRight" [theme]="theme">Text on right</div>
+</div>
+```
+
+Each directive supports two equivalent forms — pick whichever reads best:
+
+```html
+<div nContainer="Wide" [theme]="t">…</div>           <!-- aliased value -->
+<div nContainer container="Wide" [theme]="t">…</div> <!-- selector + named input -->
+```
+
+`[theme]` accepts a `FasterTheme` object **or** a theme name string. Use `<div nButton>`, not `<button nButton>`.
+
+### Service methods (alternative to directives)
+
+`FasterThemesService` exposes helpers that return CSS strings for direct `[style]` bindings — useful when you want to compose styles imperatively:
+
+```html
+<div [style]="fasterThemes.container(theme, 'Wide')">
+  <div [style]="fasterThemes.type(theme, 'H1')">Hello</div>
+  <div [style]="fasterThemes.button(theme, 'Default Style')">Click me</div>
+</div>
+```
+
+| Method | Returns |
+|---|---|
+| `container(theme, name)` | CSS for the named container style |
+| `type(theme, name)` | CSS for the named typography style |
+| `button(theme, name)` | CSS for the named button style |
+| `accordion(theme, name)` | CSS for the named accordion style |
+| `header(theme, name, expanded, index)` | CSS for an accordion header in its current state |
+| `class(theme, name)` | CSS for a named utility class |
+| `getTheme(nameOrObject)` | Resolves a name or id to its `FasterTheme` (falls back to `defaultStyle`) |
+| `getPalette(theme, paletteName)` | Looks up a palette entry by role name |
+
+All accept either a `FasterTheme` object or a theme name string.
+
+### Accordion
+
+```html
+<accordion accordionName="base" [themeName]="theme" [collapsing]="true">
+  <accordion-item *ngFor="let s of sections" [title]="s.title">
+    <ng-template accordionTitle>
+      <div nType="H4" [theme]="theme">{{ s.title }}</div>
+    </ng-template>
+    <ng-template accordionContent>
+      <div nType="body" [theme]="theme">{{ s.body }}</div>
+    </ng-template>
+  </accordion-item>
+</accordion>
+```
+
+#### `<accordion>` inputs
+
+| Input | Type | Notes |
+|---|---|---|
+| `accordionName` | `string` | Which accordion style from the theme (e.g. `base`, `Docs`) |
+| `themeName` | `FasterTheme \| string` | Theme object or theme name |
+| `collapsing` | `boolean` | Only one item open at a time |
+| `focus` | `boolean` | Other items hide while one is expanded (modal-like) |
+| `(headerClicked)` | `{ index, open }` | Emits on every toggle |
+
+`collapseAll()` is the public method to close everything.
+
+#### `<accordion-item>` inputs
+
+| Input | Notes |
+|---|---|
+| `title` | Item label, used by the default header template |
+| `disabled` | Disables expand/collapse |
+| `expanded` | Initial state |
+| `closeOther` | Title of another item to close when this one opens |
+| `loaded` | If `false`, content is lazy-loaded on first expand |
+
+### Ripple directive
+
+```html
+<div ripple style="padding: 12px;">Click anywhere</div>
+```
+
+`RippleDirective` is standalone and is auto-imported with `FasterThemesModule`. You can also import it directly into a standalone component.
+
+---
+
+## Responsive styling
+
+A major benefit of code-driven styling is that responsiveness can be expressed mathematically rather than via media-query stair-steps.
+
+Faster Themes provides seven responsive knobs per theme — `responsiveStandardWidth`, `responsiveFontSize{Min,Max}`, `responsiveMargin{Min,Max}`, `responsivePadding{Min,Max}` — that linearly interpolate text and white-space as the viewport scales. Set them via the generator inputs, the API, or directly on a theme object. End users can also adjust them at runtime if you choose to expose the controls.
+
+---
+
+## License
+Faster themes is a usage-based platform governed by a commercial license.
+
+https://fasteros.com/license
+
+## Support
+
+https://fasteros.com/support
+
+## FAQ
+
+#### Can I still use CSS & inline styling?
+
+Yes, Faster themes does not limit your use of CSS or inline styling.
+
+#### Is every CSS capability supported?
+
+Faster themes objects allow direct addition of CSS if needed so no functionality is lost.
+
+#### How many apps can we use our themes with?
+
+There is no limit.
+
+#### What is the pricing model?
+Using generated themes is free.
+
+Creating and deploying custom themes is usage based. A small team with about 10,000 end-user sessions/mo would expect to pay about $2/mo.
+
+#### What are the limits of the free version?
+
+The free version includes unlimited use of generated themes.
+
+#### Do we own a theme we develop?
+
+Yes. You can use any generated themes as a starting point to create custom themes. Any themes in your team account are your sole property.
+
+#### We reported a bug, when should we expect a fix?
+
+Faster themes is commercial software backed by a team of senior software engineers that take quality and performance very seriously. All reports of bugs are considered top priority. We also welcome all suggested improvements.
+
+#### How does this accelerate software development?
+
+Faster themes allows code to be written much faster with more consistent interfaces simply by moving styling from a static text file to code. This approach allows developers to focus on functionality and designers to make real-time improvements to the interface without the need for linear development cycles.
+
+#### Can we give our users the ability to choose or modify themes?
+
+Yes! You can let your users choose from a set of themes you create, modify themes, and offer control of responsive settings so they can optimize text and white space size.
+
+#### What about code readability?
+
+Your HTML will be self documenting and without cryptic styling shorthand.
+
+#### Is there more coming?
+
+Yes. We'll be releasing a robust set of UI elements and smart objects based on our Organic Object Model.
+
+
+<!-- [![Copyright](https://img.shields.io/badge/Copyright-©_2023--2025_Napkin_Apps_Corp._All_rights_reserved.-green)](https://fasteros.com/license) -->