@amos.com/amos-js 0.2.0 → 0.3.1

package/README.md

@@ -167,11 +167,12 @@ In short, your app orchestrates the payment flow, while sensitive payment data s
 
 ## Appearance
 
-Every mount function (and the `attach*Listeners` helpers) accepts an optional `appearance` option that controls the look of the iframe UI. It contains a `themeVariables` object whose keys are CSS custom-property names and whose values are strings. You can update appearance after page load via the controller's `update({ appearance })` method.
+Every mount function (and the `attach*Listeners` helpers) accepts an optional `appearance` option that controls the look of the iframe UI. It contains a `themeVariables` object whose keys are CSS custom-property names and whose values are strings, and an optional `labels` setting for field label placement. You can update appearance after page load via the controller's `update({ appearance })` method.
 
 ```ts
 form.update({
   appearance: {
+    labels: "floating",
     themeVariables: {
       "--primary": "oklch(0.5 0.2 240)",
       "--radius": "0.25rem",
@@ -180,7 +181,19 @@ form.update({
 });
 ```
 
-Only the variables you provide are sent; omitted variables keep their defaults.
+`themeVariables` uses a **replace** model: each update that includes `themeVariables` sets the full override set. Only the variables you list are overridden; unlisted variables revert to iframe defaults. Omit `themeVariables` to leave existing overrides unchanged.
+
+### Label placement
+
+Set `labels` to control how field labels are rendered in card and bank account forms:
+
+| Value | Behavior |
+| ----- | -------- |
+| `above` (default) | Label text above each input |
+| `floating` | Label inside the control; moves up when focused or filled |
+| `placeholder` | No visible label; placeholder and `aria-label` only |
+
+Radio groups (e.g. account type) always use an above-style group label regardless of this setting.
 
 ### Available theme variables
 
@@ -216,7 +229,7 @@ Mount the secure credit-card payment method form into a container element (an `H
 
 **Optional `options`:**
 
-- `appearance` (`{ themeVariables?: Partial<Record<ThemeVariable, string>> }`)
+- `appearance` (`{ themeVariables?: Partial<Record<ThemeVariable, string>>; labels?: "above" | "floating" | "placeholder" }`)
 - `additionalFields` (`{ cardholderName: boolean }`, defaults to `{ cardholderName: false }`)
 - `onPaymentIntentConfirmationSucceeded` (`(paymentIntent: PaymentIntent) => void`)
 - `onSetupIntentConfirmationSucceeded` (`(setupIntent: SetupIntent) => void`)

package/dist/src/index.d.ts

@@ -7,7 +7,7 @@ export type { AmosBankAccountPaymentMethodFormOptions, AmosCreditCardPaymentMeth
 export { mountAmosBankAccountPaymentMethodForm, mountAmosCreditCardPaymentMethodForm, mountAmosGooglePayButton, } from './mount';
 export type { CreditCardAdditionalFields, PaymentMethodFormController, PaymentMethodFormListenerOptions, } from './payment-method-form';
 export { attachPaymentMethodFormListeners, getBankAccountFormInitialHeight, getBankAccountFormSrc, getCreditCardFormInitialHeight, getCreditCardFormSrc, } from './payment-method-form';
-export type { Appearance, Message, ThemeVariable, } from './types';
+export type { Appearance, AppearanceLabels, Message, ThemeVariable, } from './types';
 export { createMessage } from './types';
 /**
  * Convenience alias for `components["schemas"]["CreateCustomerInput"]`.

package/dist/src/messaging.d.ts

@@ -10,8 +10,10 @@ export declare function sendParentReadyMessage(iframe: Iframe): void;
 /**
  * Push appearance overrides into the embedded iframe.
  *
- * Only the provided `themeVariables` are sent; omitted variables keep
- * their defaults.
+ * Uses a replace model for `themeVariables`: each message that includes
+ * `themeVariables` sets the full override set. Only the listed variables
+ * are overridden; unlisted variables revert to iframe defaults. Omit
+ * `themeVariables` entirely to leave existing overrides unchanged.
  */
 export declare function updateAppearance({ iframe, appearance, }: {
     iframe: Iframe;

package/dist/src/types.d.ts

@@ -5,11 +5,25 @@ import { components } from '@amos.com/node';
  * variables keep their defaults.
  */
 export type ThemeVariable = "--background" | "--foreground" | "--primary" | "--primary-foreground" | "--secondary" | "--secondary-foreground" | "--muted-foreground" | "--accent" | "--accent-foreground" | "--destructive" | "--border" | "--input" | "--input-background" | "--input-height" | "--ring" | "--radius";
+/**
+ * Placement of field labels in payment method forms.
+ *
+ * - `above` — label text is rendered above the control (default).
+ * - `floating` — label sits inside the control and shrinks when focused or filled.
+ * - `placeholder` — no visible label; use placeholder text and `aria-label` only.
+ */
+export type AppearanceLabels = "above" | "floating" | "placeholder";
 /**
  * Appearance overrides for the embedded Amos iframe UI.
  */
 export type Appearance = {
     themeVariables?: Partial<Record<ThemeVariable, string>>;
+    /**
+     * Field label placement for card and bank account forms.
+     *
+     * @default "above"
+     */
+    labels?: AppearanceLabels;
 };
 /**
  * Typed `postMessage` payloads exchanged between the host page and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amos.com/amos-js",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "main": "dist/index.js",
   "repository": {
     "type": "git",

package/src/index.ts

@@ -51,6 +51,7 @@ export {
 } from "./payment-method-form";
 export type {
   Appearance,
+  AppearanceLabels,
   Message,
   ThemeVariable,
 } from "./types";

package/src/messaging.ts

@@ -19,8 +19,10 @@ export function sendParentReadyMessage(iframe: Iframe): void {
 /**
  * Push appearance overrides into the embedded iframe.
  *
- * Only the provided `themeVariables` are sent; omitted variables keep
- * their defaults.
+ * Uses a replace model for `themeVariables`: each message that includes
+ * `themeVariables` sets the full override set. Only the listed variables
+ * are overridden; unlisted variables revert to iframe defaults. Omit
+ * `themeVariables` entirely to leave existing overrides unchanged.
  */
 export function updateAppearance({
   iframe,

package/src/types.ts

@@ -104,11 +104,26 @@ export type ThemeVariable =
    */
   | "--radius";
 
+/**
+ * Placement of field labels in payment method forms.
+ *
+ * - `above` — label text is rendered above the control (default).
+ * - `floating` — label sits inside the control and shrinks when focused or filled.
+ * - `placeholder` — no visible label; use placeholder text and `aria-label` only.
+ */
+export type AppearanceLabels = "above" | "floating" | "placeholder";
+
 /**
  * Appearance overrides for the embedded Amos iframe UI.
  */
 export type Appearance = {
   themeVariables?: Partial<Record<ThemeVariable, string>>;
+  /**
+   * Field label placement for card and bank account forms.
+   *
+   * @default "above"
+   */
+  labels?: AppearanceLabels;
 };
 
 /**