@weareconceptstudio/account 2.1.16 → 2.1.17

package/templates/account.buttons.md

@@ -0,0 +1,181 @@
+# Account button types & CSS classes
+
+Reference for `@weareconceptstudio/account` `AccountButton` — semantic `btnType` values, default BEM classes, layout, and project configuration.
+
+## Quick reference
+
+| btnType | Role | Layout | Wrapper classes | Button element classes | Legacy config key¹ |
+|---------|------|--------|-----------------|------------------------|-------------------|
+| `auth` | Sign-in, sign-up, forgot/reset password | block | `btn-wrap auth account-button-wrap account-button-wrap--auth` | `account-button account-button--auth` | — |
+| `submit` | Save changes in forms (pill) | fit | `btn-wrap submit account-button-wrap account-button-wrap--submit` | `account-button account-button--submit` | `form` |
+| `cancel` | Form / popup cancel, dismiss | fit | `btn-wrap cancel account-button-wrap account-button-wrap--cancel` | `account-button account-button--cancel` | `green-large-text` |
+| `checkout` | Proceed to checkout CTA | block | `btn-wrap checkout account-button-wrap account-button-wrap--checkout` | `account-button account-button--checkout` | — |
+| `link` | Back to shop, continue shopping | fit | `btn-wrap link account-button-wrap account-button-wrap--link` | `account-button account-button--link` | `purple-text` |
+| `link-sm` | Remove item, edit item, small actions | fit | `btn-wrap link-sm account-button-wrap account-button-wrap--link-sm` | `account-button account-button--link-sm` | `green-small-text` |
+| `link-lg` | Section Edit, product title link | fit | `btn-wrap link-lg account-button-wrap account-button-wrap--link-lg` | `account-button account-button--link-lg` | `green-large-text` |
+| `promo` | Apply promo code | fit | `btn-wrap promo account-button-wrap account-button-wrap--promo` | `account-button account-button--promo` | `promo-code-version` |
+| `balance` | Apply account balance | fit | `btn-wrap balance account-button-wrap account-button-wrap--balance` | `account-button account-button--balance` | `balance-version` |
+| `full-width` | Full-width popup primary | block | `btn-wrap full-width account-button-wrap account-button-wrap--full-width` | `account-button account-button--full-width` | `auth`, `submit` |
+| `outline` | Outlined CTA (e.g. edit review) | fit | `btn-wrap outline account-button-wrap account-button-wrap--outline` | `account-button account-button--outline` | — |
+| `icon` | Icon-only actions | fit | `btn-wrap icon account-button-wrap account-button-wrap--icon` | `account-button account-button--icon` | — |
+
+¹ **Legacy config key** — old `accountConfig.button` property name still resolved if the semantic key is missing (migration only). Do not use in new projects.
+
+## Class layers
+
+Every `AccountButton` renders with up to three hook layers:
+
+```
+.btn-wrap.{btnType}                    ← layout hooks used inside the package
+.account-button-wrap                    ← BEM block for project rewrite CSS
+.account-button-wrap--{btnType}         ← BEM modifier (one per role)
+```
+
+**Package default button** (no custom component in config):
+
+```html
+<div class="btn-wrap submit account-button-wrap account-button-wrap--submit">
+  <button class="account-button account-button--submit">
+    <div class="content-button">Save changes</div>
+  </button>
+</div>
+```
+
+**Custom project button** (`accountConfig.button.submit`):
+
+```html
+<div class="btn-wrap submit account-button-wrap account-button-wrap--submit" data-account-button-layout="block">
+  <MyButton class="account-button account-button--submit width-100 medium" />
+</div>
+```
+
+`data-account-button-layout` is `block` or `fit` — controls width inside `AccountButtonCustomWrap`.
+
+## Layout
+
+| Layout | btnTypes | Behaviour |
+|--------|----------|-----------|
+| **block** | `auth`, `checkout`, `full-width` | Full width of parent |
+| **fit** | `submit`, `cancel`, `link`, `link-sm`, `link-lg`, `promo`, `balance`, `outline`, `icon` | `width: fit-content` |
+
+## Project configuration
+
+### 1. Custom button component (per type)
+
+```ts
+import Button from '@/components/Button';
+import { createAccountButtonEntry } from '@weareconceptstudio/account/config';
+
+accountConfig: {
+  button: {
+    // Block CTAs
+    auth: createAccountButtonEntry(Button, 'auth', { className: 'width-100 medium' }),
+    submit: createAccountButtonEntry(Button, 'submit', { className: 'width-100 medium' }),
+    checkout: createAccountButtonEntry(Button, 'checkout', { className: 'width-100 medium' }),
+
+    // Link-style actions
+    'link-sm': createAccountButtonEntry(Button, 'link-sm', {
+      className: 'fonts-greenST',
+      btnType: 'float-underline',
+    }),
+
+    // Promo / balance — plain entry also works
+    promo: { component: Button, props: { className: 'medium' } },
+    balance: { component: Button, props: { className: 'medium' } },
+
+    // Omit keys you don't need — package default styles apply for:
+    // cancel, link, link-lg
+  },
+}
+```
+
+`createAccountButtonEntry(Component, variant, props)` automatically adds `account-button` + `account-button--{variant}` to the component `className`.
+
+### 2. Override BEM class tokens
+
+```ts
+accountConfig: {
+  buttonClassNames: {
+    base: 'account-button',           // default: account-button
+    wrapBase: 'account-button-wrap',  // default: account-button-wrap
+    variants: {
+      submit: 'account-button--save', // replaces account-button--submit
+    },
+    wrapVariants: {
+      submit: 'account-button-wrap--save', // optional per-type wrap modifier
+    },
+  },
+}
+```
+
+Resolved via `getAccountButtonClassName(btnType)` from `@weareconceptstudio/account/config`.
+
+### 3. Project rewrite CSS
+
+Target semantic classes (and wrap modifiers) in global rewrite styles:
+
+```css
+/* Account form — save button hover */
+.cancel-and-save-and-apply-wrap .submit,
+.cancel-and-save-and-apply-wrap .account-button-wrap--submit {
+  button:hover { /* … */ }
+}
+
+/* Cart product title — no underline */
+.cart-items-table-wrap .link-lg,
+.cart-items-table-wrap .account-button-wrap--link-lg {
+  button { text-decoration: none; }
+}
+
+/* Popup cancel — smaller text */
+.popup-content-container .cancel,
+.popup-content-container .account-button-wrap--cancel {
+  button { font-size: var(--h5); }
+}
+```
+
+Prefer `.account-button-wrap--{type}` when scoping; `.btn-wrap.{type}` also works.
+
+## Package usage map
+
+| btnType | Used in (examples) |
+|---------|-------------------|
+| `auth` | Sign-in, sign-up, forgot/reset password, verify email, unsubscribe |
+| `submit` | Account settings save, address/payment popup save, warning popup OK |
+| `cancel` | Account settings cancel, address/payment popup cancel |
+| `checkout` | TotalCheckout proceed button |
+| `link` | Cart back to shop, continue shopping, empty cart, thank-you page |
+| `link-sm` | Cart remove/edit, order list actions, address item actions |
+| `link-lg` | Account Edit, cart product title, order product link |
+| `promo` | Promo code apply |
+| `balance` | Balance apply |
+| `full-width` | Cart modification warning confirm |
+| `outline` | Order review edit (when review exists) |
+| `icon` | Order review like/dislike icons |
+
+## Exports
+
+```ts
+import {
+  ACCOUNT_BUTTON_TYPES,
+  ACCOUNT_BUTTON_LAYOUT,
+  ACCOUNT_BUTTON_CLASS_NAMES,
+  getAccountButtonLayout,
+  getAccountButtonClassName,
+  createAccountButtonEntry,
+} from '@weareconceptstudio/account/config';
+```
+
+## Migration from legacy names
+
+| Old `btnType` / config key | New |
+|----------------------------|-----|
+| `form` | `submit` |
+| `purple-text` | `link` |
+| `green-small-text` | `link-sm` |
+| `green-large-text` (edit / title) | `link-lg` |
+| `green-large-text` (cancel) | `cancel` |
+| `promo-code-version` | `promo` |
+| `balance-version` | `balance` |
+
+Update `rewrite.css` selectors in each demo project from legacy class names to the table above.

package/templates/account.config.example.ts

@@ -1,8 +1,7 @@
 /**
  * AccountProvider overrides — merged with package defaults in @weareconceptstudio/account.
  *
- * Import createAccountButtonEntry from '@weareconceptstudio/account/config'
- * and pass your project Button component in layout or here.
+ * @see ./account.buttons.md — full button types, CSS classes, layout & migration guide
  */
 import type { UserIntegrationConfig } from '@weareconceptstudio/account';
 
@@ -56,19 +55,60 @@ export const accountProviderConfig = {
 		paymentPlacement: 'review' as const,
 	},
 
-	/** Same shape as UserProvider userIntegration — optional duplicate for reference */
 	userIntegration: null as UserIntegrationConfig | null,
 
 	/**
+	 * Custom buttons — one config entry per btnType (see account.buttons.md).
+	 *
+	 * | btnType     | Layout | Wrapper modifier              | Button modifier              |
+	 * |-------------|--------|-------------------------------|------------------------------|
+	 * | auth        | block  | account-button-wrap--auth     | account-button--auth         |
+	 * | submit      | fit    | account-button-wrap--submit   | account-button--submit       |
+	 * | cancel      | fit    | account-button-wrap--cancel   | account-button--cancel       |
+	 * | checkout    | block  | account-button-wrap--checkout | account-button--checkout     |
+	 * | link        | fit    | account-button-wrap--link     | account-button--link         |
+	 * | link-sm     | fit    | account-button-wrap--link-sm  | account-button--link-sm      |
+	 * | link-lg     | fit    | account-button-wrap--link-lg  | account-button--link-lg      |
+	 * | promo       | fit    | account-button-wrap--promo    | account-button--promo        |
+	 * | balance     | fit    | account-button-wrap--balance  | account-button--balance      |
+	 * | full-width  | block  | account-button-wrap--full-width | account-button--full-width |
+	 * | outline     | fit    | account-button-wrap--outline  | account-button--outline      |
+	 * | icon        | fit    | account-button-wrap--icon     | account-button--icon         |
+	 *
+	 * @example
+	 * import Button from '@/components/Button';
+	 * import { createAccountButtonEntry } from '@weareconceptstudio/account/config';
+	 *
 	 * button: {
-	 *   auth: createAccountButtonEntry(Button, 'auth', { btnType: 'primary' }),
-	 *   form: createAccountButtonEntry(Button, 'form', { btnType: 'primary' }),
-	 *   checkout: createAccountButtonEntry(Button, 'checkout', { btnType: 'primary' }),
+	 *   auth: createAccountButtonEntry(Button, 'auth', { className: 'width-100 medium' }),
+	 *   submit: createAccountButtonEntry(Button, 'submit', { className: 'width-100 medium' }),
+	 *   checkout: createAccountButtonEntry(Button, 'checkout', { className: 'width-100 medium' }),
+	 *   'link-sm': createAccountButtonEntry(Button, 'link-sm', { btnType: 'float-underline' }),
+	 *   promo: { component: Button, props: { className: 'medium' } },
 	 * },
 	 */
 	button: {},
 
-	/** import { addressFormFields } from './address.config' */
+	/** Optional BEM overrides — merged with package defaults via getAccountButtonClassName */
+	buttonClassNames: {
+		base: 'account-button',
+		wrapBase: 'account-button-wrap',
+		variants: {
+			auth: 'account-button--auth',
+			submit: 'account-button--submit',
+			cancel: 'account-button--cancel',
+			checkout: 'account-button--checkout',
+			link: 'account-button--link',
+			'link-sm': 'account-button--link-sm',
+			'link-lg': 'account-button--link-lg',
+			promo: 'account-button--promo',
+			balance: 'account-button--balance',
+			'full-width': 'account-button--full-width',
+			outline: 'account-button--outline',
+			icon: 'account-button--icon',
+		},
+	},
+
 	addressFormFields: null,
 	addressFormFieldsShipping: null,
 	addressFormFieldsBilling: null,