Skip to Content
BBRICKSv0.7.4
BlocksGroups

SpecialCommissionForm

The "Special commission · {group}" modal body: % of sale or EGP per item, the value (1–100 % or above 0, or the caller's limits), an optional reason (300 characters), Cancel / Send to TRNDR. With mode="set" the brand sets the special commission itself: "Set special commission", the reason only with note; namesRate makes the button say "Set 15% for 4 creators" (or "… for creators who join later" on an empty group). The modal's title and hint come from the caller.

import { SpecialCommissionForm } from '@ergasti/bricks';

Examples

Ask for a special commission

A percentage or an amount per item, and a reason; TRNDR reviews it, and until then the group keeps the standard rate.

Code
import { SpecialCommissionForm } from '@ergasti/bricks';

function Ask() {
  return (
    <div style={{ maxWidth: 560 }}>
      <SpecialCommissionForm initial={{ kind: 'percent', value: '20' }} onSubmit={() => {}} onCancel={() => {}} onBackToStandard={() => {}} />
    </div>
  );
}

The commission input alone

A radio pair (percent or per item) and a number; commissionError returns the message for a value that is not allowed.

Code
import { CommissionInput, commissionError, useLanguage, type CommissionKind } from '@ergasti/bricks';
import { useState } from 'react';

function Input() {
  const language = useLanguage();
  const [kind, setKind] = useState<CommissionKind>('percent');
  const [value, setValue] = useState('120');
  return (
    <div style={{ maxWidth: 420 }}>
      <CommissionInput legend="Commission" kind={kind} value={value} onKindChange={setKind} onValueChange={setValue} error={commissionError(kind, value, language) ?? undefined} />
    </div>
  );
}

Sending and failed

saving locks the form while it is sent; error is the server's answer when sending failed. currency names the unit for "per item"; hint on CommissionInput adds a line under it.

Code
import { CommissionInput, SpecialCommissionForm, type CommissionKind } from '@ergasti/bricks';
import { useState } from 'react';

function States() {
  const [kind, setKind] = useState<CommissionKind>('per_item');
  const [value, setValue] = useState('35');
  return (
    <div style={{ display: 'grid', gap: 16, maxWidth: 560 }}>
      <SpecialCommissionForm initial={{ kind: 'per_item', value: '35' }} currency="SAR" saving onSubmit={() => {}} onCancel={() => {}} />
      <SpecialCommissionForm initial={{ kind: 'percent', value: '20' }} error="TRNDR could not receive the request. Try again." commissionLabels={{ percent: 'Share of sale' }} onSubmit={() => {}} onCancel={() => {}} />
      <CommissionInput legend="Suggested commission" kind={kind} value={value} onKindChange={setKind} onValueChange={setValue} currency="SAR" hint="Most groups get 30–40 per item." />
    </div>
  );
}

Set the special commission directly (mode="set", no TRNDR approval): a % of sale or EGP per item, "Set special commission"

note adds the optional "Why" field (sent as reason). namesRate makes the button name the rate and who it reaches ("Set 15% for 4 creators", "… for creators who join later" on an empty group). limits are the server's own bounds.

Code
import { SpecialCommissionForm } from '@ergasti/bricks';

function SetRate() {
  return (
    <div style={{ display: 'grid', gap: 24, maxWidth: 560 }}>
      <SpecialCommissionForm mode="set" note members={4} initial={{ kind: 'percent', value: '15' }} limits={{ percent: { min: '0.01', max: 50 }, perItem: { min: '0.01', max: 10000 } }}
        hint="Enter a rate from 0.01 to 50." onSubmit={() => {}} onCancel={() => {}} onBackToStandard={() => {}} />
      <SpecialCommissionForm mode="set" namesRate members={0} initial={{ kind: 'per_item', value: '30' }} onSubmit={() => {}} onCancel={() => {}} />
    </div>
  );
}

Only the kinds the server allows

kinds limits the switch (the bootstrap's group_commission.kinds); with one kind there is no switch, and a starting value of another kind starts empty on the allowed one. Default: both.

Code
import { SpecialCommissionForm } from '@ergasti/bricks';

function OneKind() {
  return (
    <div style={{ maxWidth: 560 }}>
      <SpecialCommissionForm mode="set" kinds={['percent']} members={4} onSubmit={() => {}} onCancel={() => {}} />
    </div>
  );
}

A rate in words

CommissionRate says a rate the same way on every screen: "15%" or "EGP 30 per item", trailing zeros dropped, in the provider's currency. form="long" reads "15% of sale" for a pill or a drawer row where the rate stands alone; keep the default short form in a table cell. Per item reads the same in both forms.

Code
import { CommissionRate, useLanguage } from '@ergasti/bricks';

function RateInWords() {
  const language = useLanguage();
  const rows = [['percent', '15.00'], ['per_item', '30.00'], ['percent', '12.5']] as const;
  return (
    <table className="kit-muted" style={{ borderCollapse: 'collapse' }}>
      <thead><tr><th style={{ textAlign: 'start', paddingInlineEnd: 24 }}>{language === 'ar' ? 'قصير (الافتراضي)' : 'Short (default)'}</th><th style={{ textAlign: 'start' }}>form="long"</th></tr></thead>
      <tbody>
        {rows.map(([kind, value]) => (
          <tr key={kind + value}>
            <td style={{ paddingInlineEnd: 24 }}><CommissionRate kind={kind} value={value} /></td>
            <td><CommissionRate kind={kind} value={value} form="long" /></td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}

A hint that follows the kind

hint as a function gets the chosen kind, so the line under the rate can name each kind's range. A string works as before.

Code
import { SpecialCommissionForm } from '@ergasti/bricks';

function HintByKind() {
  return (
    <div style={{ maxWidth: 560 }}>
      <SpecialCommissionForm mode="set" members={6} initial={{ kind: 'percent', value: '18' }} onSubmit={() => {}} onCancel={() => {}}
        hint={(kind) => (kind === 'per_item' ? 'From EGP 0.01 to EGP 10,000 per item.' : 'From 0.01% to 50% of each sale.')} />
    </div>
  );
}

The server's field errors

fieldErrors takes the 422 map (commission.value, kind, reason): each message sits on its field, marked invalid and focused, applied once the save ends. error is still the form-level line for an answer that has no field. Press Set special commission: the save runs, then the server refuses the rate.

Code
import { SpecialCommissionForm } from '@ergasti/bricks';
import { useState } from 'react';

function ServerErrors() {
  const [saving, setSaving] = useState(false);
  const [errors, setErrors] = useState<Record<string, string> | undefined>();
  const send = () => {
    setSaving(true);
    setTimeout(() => { setErrors({ 'commission.value': 'This group already has creators on a higher rate. Use at most 20%.' }); setSaving(false); }, 600);
  };
  return (
    <div style={{ maxWidth: 560 }}>
      <SpecialCommissionForm mode="set" members={4} initial={{ kind: 'percent', value: '25' }} saving={saving} fieldErrors={errors} onSubmit={send} onCancel={() => setErrors(undefined)} />
    </div>
  );
}

A locked input

CommissionInput disabled locks the switch and the number (the form sets it while saving); use it when the rate is shown but cannot change now.

Code
import { CommissionInput } from '@ergasti/bricks';

function InputDisabled() {
  return (
    <div style={{ maxWidth: 420 }}>
      <CommissionInput legend="Commission" kind="percent" value="15" onKindChange={() => {}} onValueChange={() => {}} disabled hint="Locked while the change is with TRNDR." />
    </div>
  );
}

Props

Prop

Type

Labels

Every word this component draws, in both languages. Override one per component and language with BricksProvider labels under the key specialCommissionForm, or with the component's own prop where it has one. A {name} is a value the component fills in.

specialCommissionForm
KeyEnglishArabic
commissionCommissionالعمولة
whyWhy (optional)السبب (اختياري)
whyPlaceholdere.g. Reward our top sellers for Q4مثلاً نكافئ أحسن البيّاعين في آخر ربع في السنة
cancelCancelإلغاء
sendSend to TRNDRابعت لـ TRNDR
sendingSending…جاري الإرسال…
backToStandardBack to standardارجع للعمولة العادية
setSet special commissionحدد عمولة خاصة
savingSaving…بنحفظ…
confirmSet 2 for 2 creatorsحدد {rate} لـ ليس رقمًا صانع محتوى

Design guidance

How the BRICKS design system uses SpecialCommissionForm. Written in docs/content/components/SpecialCommissionForm.md; the props above are read from the code, which wins where the two disagree.

The special commission modal body: "% of sale / EGP per item", the value, an optional reason and Cancel / Send to TRNDR (or, in set mode, the brand sets the rate itself); put it in a Modal titled "Special commission · <group>".

It is the mock's reqComm() modal on Brand › Creators › Groups. In the default 'ask' mode the brand asks TRNDR (reason up to 300 characters, rasp "Send to TRNDR"). In 'set' mode (the console's direct special commission, no TRNDR approval) the button is ink "Set special commission", the reason only with note, and namesRate makes it say "Set 15% for 4 creators" once the value is valid. It validates with commissionError (1–100 % or above 0 per item, or the server's limits), sends ASCII digits, and puts server 422 errors on their fields. "Back to standard" is optional (not in the mock).

Anatomy

  1. Form: form.kit-blk-form (noValidate).
  2. Commission: CommissionInput with legend "Commission", the hint and errors; disabled while saving.
  3. Why (ask mode, or set with note): FormField textarea, 3 rows, max 300, "e.g. Reward our top sellers for Q4".
  4. Error: alert line.
  5. Actions: ghost "Back to standard" pushed to the start (when given), "Cancel", submit.

Variants

PropValueLook / when
mode'ask' (default)Reason field, rasp "Send to TRNDR" ("Sending…"). Brand dashboard.
'set'Ink "Set special commission" ("Saving…"), no reason unless note. Console.
namesRatetrue (set mode)Button names the rate and reach: "Set 15% for 4 creators", "Set EGP 30 per item for creators who join later" (members={0}).
kinds['percent'] etc.Only allowed kinds; no switch with one.
limits{ percent?, perItem? }Server range; the error names it.
hintstring or (kind) => stringUnder the value; a function shows per-kind caveats.

States

StateTrigger
Invalid valuesubmit with a bad value: error under the field, focus on it, nothing sent.
Server field errorsfieldErrors keys commission, commission.value, commission.type, value, kind → commission; reason, note → Why.
Server errorerror alert.
Savingsaving: inputs and buttons disabled, aria-busy.
With Back to standardonBackToStandard.

Usage

// Brand › Creators › Groups › ask TRNDR
<Modal open title="Special commission · Top sellers" onClose={close}>
  <p className="kit-muted">The standard rate is 15% of sale. TRNDR reviews every special commission.</p>
  <SpecialCommissionForm initial={{ kind: 'percent', value: '20' }}
    onSubmit={(v) => ask.run({ groupId, ...v })} onCancel={close}
    saving={ask.pending} error={ask.error?.message} fieldErrors={ask.error?.fields} />
</Modal>
// Console: the brand sets it, naming the rate and reach
<SpecialCommissionForm mode="set" namesRate members={4} kinds={bootstrap.group_commission.kinds}
  limits={{ percent: { min: '0.01', max: 50 } }}
  hint={(k) => (k === 'per_item' ? "It never pays more than the order's item value." : 'From 0.01% to 50%.')}
  onSubmit={setRate} onCancel={close} onBackToStandard={backToStandard} />

Where it appears

  • Brand › Creators › Groups › Special commission modal (reqComm()), opened from GroupPanel (BrandCreators).

Guidelines

Do

  • Put the group's name in the modal title and the standard rate in a line above the form.
  • Use namesRate in set mode so the brand sees what it is about to change.

Don't

  • Don't prefill a value of a kind the server disallows; the form drops it.

RTL and Arabic

  • Mirrors; value LTR; Arabic-Indic digits accepted and sent as ASCII. Arabic: "ابعت لـ TRNDR", "حدد 15% لـ 4 صانع محتوى".

Tokens

Through CommissionInput, FormField, Button: --line, --card, --rasp, --ink, --bad, --focus-ring-field.

Accessibility

  • Commission is a fieldset with legend; Why is a labelled textarea; errors are tied to fields and focus moves to the first.
  • Submit has aria-busy while saving.

Found in the source

  • Roles in the markup: alert.
  • ARIA attributes set: aria-busy.
  • It moves focus in code.

Read from the component's source and tests. See Accessibility for the patterns the library follows.

See also: FormField · Button · useBricks · useLanguage · CommissionRate · GroupCard

Source

src/blocks/groups/SpecialCommissionForm.tsx (line 109) on GitHub.

On this page