Can you include a demo of calling the API with the special symbol?

The special symbol would only be used inside the methods declared to create shorthands and slots, meaning the methods resolveShorthand and getSlots from react-utilities, it should not leak for the component development itself.

I like the idea of option 2, but why not use null as the indicator of a slot that shouldn't be rendered?

The two cases are:

1. A slot that should only be rendered if the user provides content. For example, Checkbox's label slot. In this case, the defaultProps argument to resolveShorthand could be null:

label: resolveShorthand(props.label, null),

If props.label is defined, that'd override the null default:

<Checkbox label="Example" />

2. A slot that should always be rendered by default, even if the user doesn't provide content. In that case, the defaultProps argument would be non-null (an object with defaults, or an empty object {} if there are no additional defaults). For example, Checkbox's input slot:

input: resolveShorthand(props.input, { type: 'checkbox' }),

The user could override and prevent rendering the slot by passing null. This doesn't make sense in the case of Checkbox, but just as a demo:

<Checkbox input={null} />

One possible problem with that: what about the case of optional slot that have default properties?

That's case 2 in my example above. It provides default props { type: 'checkbox' }, but can be explicitly set to null by the user: input={null}. To implement, resolveShorthand would just check the first argument for null and return null in that case.

There is a case 3, which is a slot that always must be rendered and can never be prevented from rendering (e.g. root). In that case, we'd simply not include null in the possible type for that slot.

alwaysRenderedSlot: React.HTMLAttributes<HTMLElement>;
optionallyRenderedSlot: React.HTMLAttributes<HTMLElement> | null;

This is just a copy of the pro above, is that intended?

Yes, it's intentional. Making shorthand logic more explicit can be considered a pro but also a con depending on the POV

To avoid confusion, as I was also wondering, I would avoid repeating the same phrase and instead go with something like:

Optionally we can modify resolveShorthand's signature, to have second param as config:

resolveShorthand(props.slot2, {
  optional: false,
  defaultProps: { "aria-label": "foo" }
});

hmmm, there's always the possibility that optional is actually a property from the slot, and that would generate a conflict hehehe, but yeah, we could assume that slots can't have optional as prop

Props in this case will be defined under a separate property (defaultProps), so they will not collide 😉

Totally agree with this idea

what @layershifter said , adding any kind of positional arguments makes API less readable/hard to maintain/brittle to breaking changes