feat(template): add template ux metadata v1

Author: ruicore

README-pypi.md

@@ -69,14 +69,23 @@ class Importer(BaseModel):
     email: Annotated[
         Email,
         Field(min_length=10),
-        ExcelMeta(label='Email', order=1, hint='Use your work email'),
+        ExcelMeta(
+            label='Email',
+            order=1,
+            hint='Use your work email',
+            example_value='alice@company.com',
+        ),
     ]
 
 
 alchemy = ExcelAlchemy(ImporterConfig(Importer, locale='en'))
 template = alchemy.download_template_artifact(filename='people-template.xlsx')
 ```
 
+This template metadata is additive: it leaves the worksheet layout alone and
+improves the generated header comment with both guidance text and a concrete
+example value.
+
 ## Example Outputs
 
 These fixed outputs are generated from the repository examples by

README.md

@@ -71,14 +71,23 @@ class Importer(BaseModel):
     email: Annotated[
         Email,
         Field(min_length=10),
-        ExcelMeta(label='Email', order=1, hint='Use your work email'),
+        ExcelMeta(
+            label='Email',
+            order=1,
+            hint='Use your work email',
+            example_value='alice@company.com',
+        ),
     ]
 
 
 alchemy = ExcelAlchemy(ImporterConfig(Importer, locale='en'))
 template = alchemy.download_template_artifact(filename='people-template.xlsx')
 ```
 
+This template metadata is additive: it keeps the worksheet layout unchanged and
+adds clearer header comments for spreadsheet users, such as a free-form hint
+and a concrete example value.
+
 For browser downloads, prefer `template.as_bytes()` with a `Blob`, or return the bytes from your backend with
 `Content-Disposition: attachment`. A top-level navigation to a long `data:` URL is less reliable in modern browsers.
 

docs/getting-started.md

@@ -75,6 +75,29 @@ class EmployeeImporter(BaseModel):
     age: Annotated[Number, Field(ge=18), ExcelMeta(label='Age', order=2)]
 ```
 
+If you want generated templates to give users a more concrete example before
+upload, you can add template UX metadata such as `hint` and `example_value`:
+
+```python
+class EmployeeImporter(BaseModel):
+    work_email: Annotated[
+        String,
+        Field(min_length=8),
+        ExcelMeta(
+            label='Work email',
+            order=3,
+            hint='Use your company email address',
+            example_value='alice@company.com',
+        ),
+    ]
+```
+
+This is additive. It does not change import behavior or worksheet layout. It
+only adds a more helpful header comment in the generated template, for example:
+
+- `Hint: Use your company email address`
+- `Example: alice@company.com`
+
 ## 4. Pick The Workflow You Need
 
 Import-only create flow:

docs/public-api.md

@@ -30,6 +30,8 @@ These modules are the recommended import paths for application code:
 - `excelalchemy.metadata`
   Public metadata entry points such as `FieldMeta(...)`, `ExcelMeta(...)`, and
   `PatchFieldMeta`.
+  Template guidance metadata such as `hint=` and `example_value=` is part of
+  this additive public surface.
 - `excelalchemy.results`
   Structured import result models such as `ImportResult`,
   `ValidateResult`, and `ValidateHeaderResult`.

examples/README.md

@@ -32,6 +32,7 @@ Use them to understand how the library is intended to be used from application c
 
 - `examples/annotated_schema.py`
   - Demonstrates the modern `Annotated[..., Field(...), ExcelMeta(...)]` declaration style.
+  - Shows additive template UX metadata such as `hint=` and `example_value=`.
   - Type: demo of the recommended declaration style.
 
 - `examples/employee_import_workflow.py`

examples/annotated_schema.py

@@ -11,13 +11,18 @@ class EmployeeImporter(BaseModel):
     full_name: Annotated[
         String,
         Field(min_length=2),
-        ExcelMeta(label='Full name', order=1, hint='Use the legal name'),
+        ExcelMeta(label='Full name', order=1, hint='Use the legal name', example_value='Alice Chen'),
     ]
     age: Annotated[Number, Field(ge=18), ExcelMeta(label='Age', order=2)]
     work_email: Annotated[
         Email,
         Field(min_length=8),
-        ExcelMeta(label='Work email', order=3, hint='Use your company email address'),
+        ExcelMeta(
+            label='Work email',
+            order=3,
+            hint='Use your company email address',
+            example_value='alice.chen@company.com',
+        ),
     ]
 
 

files/example-outputs/annotated-schema.txt

@@ -1 +1 @@
-Generated template: employee-template.xlsx (6803 bytes)
+Generated template: employee-template.xlsx (6853 bytes)

files/example-outputs/custom-storage.txt

@@ -1,2 +1,2 @@
 memory://employees.xlsx
-Uploaded bytes: 6813
+Uploaded bytes: 6836

files/example-outputs/date-and-range-fields.txt

@@ -1,2 +1,2 @@
-Generated template: compensation-template.xlsx (6862 bytes)
+Generated template: compensation-template.xlsx (6882 bytes)
 Fields: Start date, Probation window, Salary band, Signing bonus

files/example-outputs/export-workflow.txt

@@ -1,5 +1,5 @@
 Export workflow completed
 Artifact filename: employees-export.xlsx
-Artifact bytes: 6893
+Artifact bytes: 6909
 Upload URL: memory://employees-export-upload.xlsx
 Uploaded objects: ['employees-export-upload.xlsx']