@aurodesignsystem-dev/auro-formkit 0.0.0-pr1483.1 → 0.0.0-pr1483.11

package/components/datepicker/demo/customize.md

@@ -19,7 +19,8 @@
 <auro-anchorlink fluid href="#customValidation" class="level2 body-xs">Custom Validation</auro-anchorlink>
 <auro-anchorlink fluid href="#noValidate" class="level2 body-xs">No Validation</auro-anchorlink>
 <auro-anchorlink fluid href="#minMaxDate" class="level2 body-xs">Min/Max Date</auro-anchorlink>
-<auro-anchorlink fluid href="#localization" class="level2 body-xs">Localization</auro-anchorlink>
+<auro-anchorlink fluid href="#regionalDate" class="level2 body-xs">Regional Date</auro-anchorlink>
+<auro-anchorlink fluid href="#monthNames" class="level2 body-xs">Month Names</auro-anchorlink>
 </auro-nav>
 </nav>
 <div class="mainContent">
@@ -694,27 +695,72 @@
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 <auro-header level="3" id="localization">Localization</auro-header>
-<p>Use the <code>centralDate</code>, locale, and related attributes to configure the datepicker for different regions and languages.</p>
+<auro-header level="4" id="regionalDate">Regional Date</auro-header>
+<p>When the <code>locale</code> attribute is set, the component automatically derives the correct date format for that region — no need to set <code>format</code> manually. For example, <code>locale="en-US"</code> produces <code>mm/dd/yyyy</code>, <code>locale="de-DE"</code> produces <code>dd.mm.yyyy</code>, and <code>locale="ja-JP"</code> produces <code>yyyy/mm/dd</code>.</p>
+<p>If <code>format</code> is explicitly set alongside <code>locale</code>, <code>format</code> always wins. Use this when a specific format is required regardless of region.</p>
+<p>If no <code>locale</code> attribute is set on the element, the component walks up the DOM looking for the nearest ancestor with a <code>data-locale</code> attribute and uses that value. If none is found, it defaults to <code>en-US</code>.</p>
+<auro-header level="4" id="monthNames">Month Names</auro-header>
+<p>The <code>monthNames</code> attribute accepts an array of 12 month name strings displayed in the calendar header. When <code>monthNames</code> is <strong>not</strong> set, the component automatically derives localized month names from the active <code>locale</code> (falling back to <code>en-US</code> if no locale is set).</p>
+<p>Use <code>monthNames</code> only when you need to override the locale-derived names — for example, to supply translated names that differ from the browser's built-in <code>Intl</code> output, or to support a locale the browser does not recognize.</p>
+<pre><code>// Override month names (all 12 required, starting with January)
+datepicker.monthNames = [
+  'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
+];</code></pre>
 <div class="exampleWrapper">
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/localization.html) -->
-<!-- The below content is automatically added from ./../apiExamples/localization.html -->
-<auro-datepicker format="yyyy/mm/dd" id="localizationExample">
-<span slot="bib.fullscreen.headline">Localization Headline</span>
-<span slot="fromLabel">Choose a date</span>
-<span slot="bib.fullscreen.fromLabel">Choose a date</span>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/locale.html) -->
+<!-- The below content is automatically added from ./../apiExamples/locale.html -->
+<div data-locale="de-DE">
+<auro-datepicker locale="en-US">
+<span slot="fromLabel">en-US Date</span>
+<span slot="helpText">Help Text</span>
+</auro-datepicker>
+<auro-datepicker locale="de-DE">
+<span slot="fromLabel">de-DE Date</span>
+<span slot="helpText">Help Text</span>
+</auro-datepicker>
+<auro-datepicker locale="zh-CN">
+<span slot="fromLabel">zh-CN Date</span>
+<span slot="helpText">Help Text</span>
+</auro-datepicker>
+<auro-datepicker>
+<span slot="fromLabel">Nearest `data-locale` attribute format (`de-DE` in this case)</span>
+<span slot="helpText">Help Text</span>
+</auro-datepicker>
+<auro-datepicker locale="ja-JP" format="mm/dd/yyyy">
+<span slot="fromLabel">ja-JP locale with explicit mm/dd/yyyy format</span>
+<span slot="helpText">Help Text</span>
 </auro-datepicker>
+</div>
 <!-- AURO-GENERATED-CONTENT:END -->
 </div>
 <auro-accordion alignRight>
 <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/localization.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/localization.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/locale.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/locale.html -->
 
-<pre class="language-html"><code class="language-html">&lt;auro-datepicker format="yyyy/mm/dd" id="localizationExample"&gt;
-  &lt;span slot="bib.fullscreen.headline"&gt;Localization Headline&lt;/span&gt;
-  &lt;span slot="fromLabel"&gt;Choose a date&lt;/span&gt;
-  &lt;span slot="bib.fullscreen.fromLabel"&gt;Choose a date&lt;/span&gt;
-&lt;/auro-datepicker&gt;</code></pre>
+<pre class="language-html"><code class="language-html">&lt;div data-locale="de-DE"&gt;
+  &lt;auro-datepicker locale="en-US"&gt;
+    &lt;span slot="fromLabel"&gt;en-US Date&lt;/span&gt;
+    &lt;span slot="helpText"&gt;Help Text&lt;/span&gt;
+  &lt;/auro-datepicker&gt;
+  &lt;auro-datepicker locale="de-DE"&gt;
+    &lt;span slot="fromLabel"&gt;de-DE Date&lt;/span&gt;
+    &lt;span slot="helpText"&gt;Help Text&lt;/span&gt;
+  &lt;/auro-datepicker&gt;
+  &lt;auro-datepicker locale="zh-CN"&gt;
+    &lt;span slot="fromLabel"&gt;zh-CN Date&lt;/span&gt;
+    &lt;span slot="helpText"&gt;Help Text&lt;/span&gt;
+  &lt;/auro-datepicker&gt;
+  &lt;auro-datepicker&gt;
+    &lt;span slot="fromLabel"&gt;Nearest `data-locale` attribute format (`de-DE` in this case)&lt;/span&gt;
+    &lt;span slot="helpText"&gt;Help Text&lt;/span&gt;
+  &lt;/auro-datepicker&gt;
+  &lt;auro-datepicker locale="ja-JP" format="mm/dd/yyyy"&gt;
+    &lt;span slot="fromLabel"&gt;ja-JP locale with explicit mm/dd/yyyy format&lt;/span&gt;
+    &lt;span slot="helpText"&gt;Help Text&lt;/span&gt;
+  &lt;/auro-datepicker&gt;
+&lt;/div&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 </section>

package/components/datepicker/demo/index.md

@@ -10,6 +10,7 @@
 <auro-anchorlink fluid href="#selectRange" class="level2 body-xs">Select a Range</auro-anchorlink>
 <auro-anchorlink fluid href="#presetValue" class="level2 body-xs">Preset Value</auro-anchorlink>
 <auro-anchorlink fluid href="#skipSelection" class="level2 body-xs">Skip Selection</auro-anchorlink>
+<auro-anchorlink fluid href="#regionalDateFormat" class="level2 body-xs">Regional Date</auro-anchorlink>
 <auro-anchorlink fluid href="#viewportSize" class="level2 body-xs">Viewport Size</auro-anchorlink>
 </auro-nav>
 </nav>
@@ -167,6 +168,28 @@
 <auro-header level="3" id="skipSelection">Skip selection</auro-header>
 <p>The datepicker does not force the user to select a date. If no selection is made and the field is not <code>required</code>, the user can move past the datepicker without entering a value.</p>
 <p>If the field is <code>required</code>, moving focus away without selecting a date triggers validation and renders the <code>valueMissing</code> error state.</p>
+<auro-header level="3" id="regionalDateFormat">Regional date format support</auro-header>
+<p>People around the world write dates differently. A traveler in the United States expects to see <strong>12/25/2025</strong>, while someone in Germany expects <strong>25.12.2025</strong>, and someone in Japan expects <strong>2025/12/25</strong>. Showing the wrong format causes confusion and mistakes.</p>
+<p>When the datepicker knows the user's region via the <code>locale</code> attribute, it automatically displays dates in the format that looks natural to them — no extra setup required.</p>
+<div class="exampleWrapper">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/locale-single.html) -->
+<!-- The below content is automatically added from ./../apiExamples/locale-single.html -->
+<auro-datepicker locale="zh-CN">
+<span slot="fromLabel">zh-CN Date</span>
+<span slot="helpText">Help Text</span>
+</auro-datepicker>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+<span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/locale-single.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/locale-single.html -->
+<pre class="language-html"><code class="language-html">&lt;auro-datepicker locale="zh-CN"&gt;
+  &lt;span slot="fromLabel"&gt;zh-CN Date&lt;/span&gt;
+  &lt;span slot="helpText"&gt;Help Text&lt;/span&gt;
+&lt;/auro-datepicker&gt;</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
 <auro-header level="3" id="viewportSize">Viewport size</auro-header>
 <p>The datepicker automatically adapts its presentation based on viewport size. On larger screens, the calendar opens in a floating popover anchored to the trigger. On smaller screens, the calendar opens in a fullscreen dialog.</p>
 <p>The breakpoint at which the fullscreen behavior activates is controlled by the <code>fullscreenBreakpoint</code> attribute. The default value is <code>sm</code>. Supported values are <code>xs</code>, <code>sm</code>, <code>md</code>, <code>lg</code>, <code>xl</code>, and <code>disabled</code>.</p>